typsphinx 0.3.0__py3-none-any.whl

typsphinx/__init__.py

@@ -0,0 +1,58 @@
+"""
+Sphinx Typst Extension
+=======================
+
+A Sphinx extension that provides Typst output format support.
+
+This extension allows you to generate Typst documents from reStructuredText
+sources using Sphinx, which can then be compiled to PDF using the Typst compiler.
+
+:copyright: Copyright 2024 by Sphinx Typst Contributors
+:license: MIT, see LICENSE for details.
+"""
+
+__version__ = "0.3.0"
+__author__ = "Sphinx Typst Contributors"
+
+from typing import Any, Dict
+
+from sphinx.application import Sphinx
+
+from typsphinx.builder import TypstBuilder, TypstPDFBuilder
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """
+    Sphinx extension setup function.
+
+    This function will be called by Sphinx to register the extension.
+
+    Args:
+        app: The Sphinx application instance
+
+    Returns:
+        Extension metadata dictionary
+    """
+    app.add_builder(TypstBuilder)
+    app.add_builder(TypstPDFBuilder)
+
+    # Register configuration values
+    app.add_config_value("typst_documents", [], "html", [list])
+    app.add_config_value("typst_template", None, "html", [str, type(None)])
+    app.add_config_value("typst_template_mapping", None, "html", [dict, type(None)])
+    app.add_config_value("typst_toctree_defaults", None, "html", [dict, type(None)])
+    app.add_config_value("typst_use_mitex", True, "html", [bool])
+    app.add_config_value("typst_elements", {}, "html", [dict])
+    # Task 13.4: Other configuration options (Requirement 8.6)
+    app.add_config_value("typst_package", None, "html", [str, type(None)])
+    app.add_config_value("typst_package_imports", None, "html", [list, type(None)])
+    app.add_config_value("typst_template_function", None, "html", [str, type(None)])
+    # Task 13.4: Output directory and debug mode
+    app.add_config_value("typst_output_dir", "_build/typst", "html", [str])
+    app.add_config_value("typst_debug", False, "html", [bool])
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

typsphinx/builder.py

@@ -0,0 +1,322 @@
+"""
+Typst builder for Sphinx.
+
+This module implements the TypstBuilder class, which is responsible for
+building Typst output from Sphinx documentation.
+"""
+
+from collections.abc import Iterator
+from os import path
+from typing import Optional, Set
+
+from docutils import nodes
+from sphinx.builders import Builder
+from sphinx.util import logging
+from sphinx.util.osutil import ensuredir
+
+from typsphinx.pdf import compile_typst_to_pdf
+from typsphinx.writer import TypstWriter
+
+logger = logging.getLogger(__name__)
+
+
+class TypstBuilder(Builder):
+    """
+    Builder class for Typst output format.
+
+    This builder converts Sphinx documentation to Typst markup files (.typ),
+    which can then be compiled to PDF using the Typst compiler.
+    """
+
+    name = "typst"
+    format = "typst"
+    out_suffix = ".typ"
+    allow_parallel = True
+
+    def init(self) -> None:
+        """
+        Initialize the builder.
+
+        This method is called once at the beginning of the build process.
+        """
+        pass
+
+    def get_outdated_docs(self) -> Iterator[str]:
+        """
+        Return an iterator of document names that need to be rebuilt.
+
+        For now, we rebuild all documents on every build.
+
+        Returns:
+            Iterator of document names that are outdated
+        """
+        for docname in self.env.found_docs:
+            yield docname
+
+    def get_target_uri(self, docname: str, typ: Optional[str] = None) -> str:
+        """
+        Return the target URI for a document.
+
+        Args:
+            docname: Name of the document
+            typ: Type of the target (not used for Typst builder)
+
+        Returns:
+            Target URI string
+        """
+        return docname + self.out_suffix
+
+    def prepare_writing(self, docnames: Set[str]) -> None:
+        """
+        Prepare for writing the documents.
+
+        This method is called before writing begins.
+        Writes the template file to the output directory for master documents to import.
+
+        Args:
+            docnames: Set of document names to be written
+        """
+        # Create the writer instance
+        self.writer = TypstWriter(self)
+
+        # Write template file for master documents to import
+        self._write_template_file()
+
+    def write(
+        self,
+        build_docnames: Optional[Set[str]],
+        updated_docnames: Set[str],
+        method: str = "update",
+    ) -> None:
+        """
+        Override write() to preserve toctree nodes.
+
+        By default, Sphinx's Builder.write() calls env.get_and_resolve_doctree()
+        which expands toctree nodes into compact_paragraph with links.
+        For Typst, we need the original toctree nodes to generate #include() directives.
+
+        This method uses env.get_doctree() instead to preserve toctree nodes.
+
+        Args:
+            build_docnames: Document names to build (None = all)
+            updated_docnames: Document names that were updated
+            method: Build method ('update' or 'all')
+        """
+        if build_docnames is None or build_docnames == ["__all__"]:
+            # build_all
+            build_docnames = self.env.found_docs
+        if method == "update":
+            # build updated and specified
+            docnames = set(build_docnames) | set(updated_docnames)
+        else:
+            # build all
+            docnames = set(build_docnames)
+
+        logger.info("preparing documents... ", nonl=True)
+        self.prepare_writing(docnames)
+        logger.info("done")
+
+        # Write individual documents
+        warnings_count = 0
+        for docname in sorted(docnames):
+            # Use env.get_doctree() instead of env.get_and_resolve_doctree()
+            # to preserve toctree nodes (Requirement 13.2)
+            doctree = self.env.get_doctree(docname)
+            self.env.apply_post_transforms(doctree, docname)
+
+            # Log progress
+            logger.info(f"writing output... [{docname}]", nonl=True)
+
+            # Write the document
+            self.write_doc(docname, doctree)
+
+            logger.info(" done")
+
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
+        """
+        Write a document.
+
+        This method is called for each document that needs to be written.
+
+        Requirement 13.1: 各 reStructuredText ファイルに対応する独立した
+        .typ ファイルを生成する
+
+        Requirement 13.12: ソースディレクトリ構造を保持して出力する
+
+        Args:
+            docname: Name of the document
+            doctree: Document tree to be written
+        """
+        # Get the output file path
+        destination = path.join(self.outdir, docname + self.out_suffix)
+
+        # Ensure the directory for this specific file exists
+        # This handles nested paths like "chapter1/section"
+        dest_dir = path.dirname(destination)
+        ensuredir(dest_dir)
+
+        # Set current docname for template application logic
+        self.current_docname = docname
+
+        # Set the document on the writer
+        self.writer.document = doctree
+
+        # Translate the document to Typst markup
+        self.writer.translate()
+
+        # Save the output to the file
+        with open(destination, "w", encoding="utf-8") as f:
+            f.write(self.writer.output)
+
+    def _write_template_file(self) -> None:
+        """
+        Write the template file to the output directory.
+
+        This writes a separate template.typ file that master documents can import.
+        Only writes if a template is configured (not using Typst Universe packages).
+        """
+        from typsphinx.template_engine import TemplateEngine
+
+        config = self.config
+
+        # Get template configuration
+        template_path = getattr(config, "typst_template", None)
+        if template_path:
+            # Resolve relative path from source directory
+            import os
+
+            template_path = os.path.join(self.srcdir, template_path)
+
+        # Skip if using Typst Universe package (no separate template file needed)
+        typst_package = getattr(config, "typst_package", None)
+        if typst_package:
+            return
+
+        # Create template engine
+        template_engine = TemplateEngine(
+            template_path=template_path,
+            search_paths=[self.srcdir],
+            parameter_mapping=getattr(config, "typst_template_mapping", None),
+            typst_package=typst_package,
+            typst_template_function=getattr(config, "typst_template_function", None),
+            typst_package_imports=getattr(config, "typst_package_imports", None),
+        )
+
+        # Get template content
+        template_content = template_engine.get_template_content()
+
+        # Write template file
+        template_file_path = path.join(self.outdir, "_template.typ")
+        with open(template_file_path, "w", encoding="utf-8") as f:
+            f.write(template_content)
+
+        logger.info(f"Template written to {template_file_path}")
+
+    def finish(self) -> None:
+        """
+        Finish the build process.
+
+        This method is called once after all documents have been written.
+        """
+        pass
+
+
+class TypstPDFBuilder(TypstBuilder):
+    """
+    Builder class for generating PDF output directly from Typst.
+
+    This builder extends TypstBuilder to compile generated .typ files
+    to PDF using the typst-py package.
+
+    Requirement 9.3: TypstPDFBuilder extends TypstBuilder
+    Requirement 9.4: Generate PDF from Typst markup
+    """
+
+    name = "typstpdf"
+    format = "pdf"
+    out_suffix = ".pdf"
+
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
+        """
+        Write a document as both .typ and .pdf.
+
+        Override to generate .typ file (not .pdf) during the write phase.
+        The .pdf will be generated in finish() by compiling the .typ file.
+
+        Args:
+            docname: Name of the document
+            doctree: Document tree to be written
+        """
+        # Generate .typ file (not .pdf)
+        typ_destination = path.join(self.outdir, docname + ".typ")
+
+        # Ensure the directory exists
+        dest_dir = path.dirname(typ_destination)
+        ensuredir(dest_dir)
+
+        # Set current docname for template application logic
+        self.current_docname = docname
+
+        # Set the document on the writer
+        self.writer.document = doctree
+
+        # Translate the document to Typst markup
+        self.writer.translate()
+
+        # Save the .typ file
+        with open(typ_destination, "w", encoding="utf-8") as f:
+            f.write(self.writer.output)
+
+    def finish(self) -> None:
+        """
+        Finish the build process by compiling Typst files to PDF.
+
+        After the parent TypstBuilder has generated .typ files,
+        this method compiles them to PDF using typst-py.
+
+        Only master documents (defined in typst_documents) are compiled to PDF.
+        Included documents are not compiled individually.
+
+        Requirement 9.2: Execute Typst compilation within Python
+        Requirement 9.4: Generate PDF from Typst markup
+        """
+        # First, call parent finish() to complete .typ generation
+        super().finish()
+
+        # Get master documents from typst_documents config
+        typst_documents = getattr(self.config, "typst_documents", [])
+
+        if not typst_documents:
+            logger.warning(
+                "No documents defined in typst_documents. Nothing to compile."
+            )
+            return
+
+        logger.info(f"Compiling {len(typst_documents)} master document(s) to PDF...")
+
+        for doc_tuple in typst_documents:
+            # doc_tuple format: (sourcename, targetname, title, author)
+            docname = doc_tuple[0]
+            typ_file = path.join(self.outdir, docname + ".typ")
+
+            if not path.exists(typ_file):
+                logger.warning(f"Master document not found: {typ_file}")
+                continue
+
+            try:
+                # Read Typst content
+                with open(typ_file, encoding="utf-8") as f:
+                    typst_content = f.read()
+
+                # Compile to PDF
+                pdf_bytes = compile_typst_to_pdf(typst_content, root_dir=self.outdir)
+
+                # Write PDF file
+                pdf_file = path.join(self.outdir, docname + ".pdf")
+                with open(pdf_file, "wb") as f:
+                    f.write(pdf_bytes)
+
+                logger.info(f"Generated PDF: {pdf_file}")
+
+            except Exception as e:
+                logger.error(f"Failed to compile {typ_file}: {e}")

typsphinx/pdf.py

@@ -0,0 +1,192 @@
+"""
+PDF generation utilities using typst-py.
+
+This module provides functionality for generating PDFs from Typst markup
+using the typst Python package (Requirement 9).
+"""
+
+import logging
+import os
+import tempfile
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class TypstCompilationError(Exception):
+    """
+    Exception raised when Typst compilation fails.
+
+    This exception provides detailed information about compilation errors,
+    including the original error from typst-py and contextual information.
+
+    Attributes:
+        message: Human-readable error message
+        typst_error: Original error from typst compiler
+        source_location: Location information if available
+
+    Requirement 10.3: Error detection and handling
+    Requirement 10.4: Error message parsing and user display
+    """
+
+    def __init__(
+        self,
+        message: str,
+        typst_error: Optional[Exception] = None,
+        source_location: Optional[str] = None,
+    ):
+        """
+        Initialize TypstCompilationError.
+
+        Args:
+            message: Human-readable error description
+            typst_error: Original exception from typst compiler
+            source_location: Source file location information
+        """
+        self.message = message
+        self.typst_error = typst_error
+        self.source_location = source_location
+
+        # Build full error message
+        full_message = f"Typst compilation failed: {message}"
+        if source_location:
+            full_message += f"\nLocation: {source_location}"
+        if typst_error:
+            full_message += f"\nDetails: {str(typst_error)}"
+
+        super().__init__(full_message)
+
+
+def check_typst_available() -> None:
+    """
+    Check if typst package is available.
+
+    Raises:
+        ImportError: If typst package is not installed
+
+    Requirement 9.1: Typst compiler functionality as dependency
+    Requirement 9.7: Automatic availability of Typst compiler
+    """
+    try:
+        import typst  # noqa: F401
+    except ImportError as e:
+        raise ImportError(
+            "typst package not found. Please install it:\n"
+            "  pip install typst\n"
+            "Or install typsphinx with PDF support:\n"
+            "  pip install typsphinx[pdf]"
+        ) from e
+
+
+def get_typst_version() -> str:
+    """
+    Get the version of the typst package.
+
+    Returns:
+        Version string (e.g., "0.13.7")
+
+    Requirement 9.7: Version information for Typst compiler
+    """
+    try:
+        import typst
+
+        # Try to get version from __version__ attribute
+        if hasattr(typst, "__version__"):
+            return typst.__version__
+
+        # Try to get from package metadata
+        try:
+            from importlib.metadata import version
+
+            return version("typst")
+        except Exception:
+            pass
+
+        # Fallback
+        return "unknown"
+    except ImportError:
+        return "not installed"
+
+
+def compile_typst_to_pdf(typst_content: str, root_dir: Optional[str] = None) -> bytes:
+    """
+    Compile Typst content to PDF bytes.
+
+    Args:
+        typst_content: Typst markup content
+        root_dir: Root directory for resolving includes and images
+
+    Returns:
+        PDF content as bytes
+
+    Raises:
+        ImportError: If typst package not available
+        TypstCompilationError: If compilation fails
+
+    Requirement 9.2: Execute Typst compilation within Python environment
+    Requirement 9.4: Generate PDF from Typst markup
+    Requirement 10.3: Error detection and handling
+    """
+    check_typst_available()
+
+    import typst
+
+    # Create a temporary file for the Typst content
+    # typst.compile() requires a file path, not string content
+    temp_file = None
+    try:
+        # Create temporary file in root_dir if specified, otherwise use system temp
+        temp_dir = root_dir if root_dir else None
+
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".typ", dir=temp_dir, delete=False, encoding="utf-8"
+        ) as f:
+            f.write(typst_content)
+            temp_file = f.name
+
+        # Compile Typst file to PDF
+        # The typst.compile() function takes a file path and returns PDF bytes
+        try:
+            pdf_bytes = typst.compile(temp_file, root=root_dir)
+            return pdf_bytes
+        except Exception as typst_error:
+            # Parse and wrap the error with more context
+            error_msg = _parse_typst_error(typst_error)
+            source_loc = temp_file if temp_file else "unknown"
+
+            logger.error(f"Typst compilation failed at {source_loc}: {error_msg}")
+
+            raise TypstCompilationError(
+                message=error_msg, typst_error=typst_error, source_location=source_loc
+            ) from typst_error
+
+    finally:
+        # Clean up temporary file
+        if temp_file and os.path.exists(temp_file):
+            try:
+                os.unlink(temp_file)
+            except Exception:
+                pass  # Ignore cleanup errors
+
+
+def _parse_typst_error(error: Exception) -> str:
+    """
+    Parse Typst compiler error to extract useful information.
+
+    Args:
+        error: Original exception from typst compiler
+
+    Returns:
+        Human-readable error message
+
+    Requirement 10.4: Error message parsing
+    """
+    error_str = str(error)
+
+    # Extract meaningful information from error
+    # Typst errors often contain detailed information
+    if not error_str:
+        return f"{type(error).__name__}"
+
+    # Return the error string with type information
+    return f"{type(error).__name__}: {error_str}"