typsphinx 0.3.0__py3-none-any.whl

typsphinx/writer.py

@@ -0,0 +1,144 @@
+"""
+Typst writer for docutils.
+
+This module implements the TypstWriter class, which converts docutils
+document trees to Typst markup.
+"""
+
+from typing import Any
+
+from docutils import writers
+
+from typsphinx.template_engine import TemplateEngine
+from typsphinx.translator import TypstTranslator
+
+
+class TypstWriter(writers.Writer):
+    """
+    Writer class for Typst output format.
+
+    This writer converts docutils document trees to Typst markup files.
+    """
+
+    supported = ("typst",)
+    """Formats this writer supports."""
+
+    def __init__(self, builder: Any) -> None:
+        """
+        Initialize the writer.
+
+        Args:
+            builder: The Sphinx builder instance
+        """
+        super().__init__()
+        self.builder = builder
+
+    def _is_master_document(self, docname: str) -> bool:
+        """
+        Check if the current document is a master document (defined in typst_documents).
+
+        Master documents should have templates applied, while included documents
+        (via #include()) should only contain body content.
+
+        Args:
+            docname: Document name (e.g., 'index', 'chapter1')
+
+        Returns:
+            True if this is a master document, False otherwise
+        """
+        config = self.builder.config
+        typst_documents = getattr(config, "typst_documents", [])
+
+        # Check if docname is in typst_documents
+        # typst_documents format: [(sourcename, targetname, title, author), ...]
+        for doc_tuple in typst_documents:
+            if doc_tuple[0] == docname:
+                return True
+
+        return False
+
+    def translate(self) -> None:
+        """
+        Translate the document tree to Typst markup.
+
+        This method creates a TypstTranslator and visits the document tree,
+        then wraps the output with a template using TemplateEngine.
+
+        For master documents (defined in typst_documents), the full template
+        is applied. For included documents, only the body content is output.
+        """
+        # Generate body content
+        self.visitor = TypstTranslator(self.document, self.builder)
+        self.document.walkabout(self.visitor)
+        body = self.visitor.astext()
+
+        # Get current document name
+        docname = self.builder.current_docname
+
+        # Check if this is a master document
+        is_master = self._is_master_document(docname)
+
+        if not is_master:
+            # For included documents, add essential imports but no template
+            # Typst's #include() does not inherit imports from parent file,
+            # so each file needs its own imports
+            imports = []
+            imports.append("// Essential imports for included document")
+            imports.append('#import "@preview/codly:1.3.0": *')
+            imports.append('#import "@preview/codly-languages:0.1.1": *')
+            imports.append('#import "@preview/mitex:0.2.4": mi, mitex')
+            imports.append('#import "@preview/gentle-clues:1.2.0": *')
+            imports.append("")
+            imports.append("// Initialize codly")
+            imports.append("#show: codly-init.with()")
+            imports.append("#codly(languages: codly-languages)")
+            imports.append("")
+
+            self.output = "\n".join(imports) + "\n" + body
+            return
+
+        # For master documents, apply template
+        config = self.builder.config
+
+        # Get template configuration from Sphinx config
+        template_path = getattr(config, "typst_template", None)
+        if template_path:
+            # Resolve relative path from source directory
+            import os
+
+            source_dir = self.builder.srcdir
+            template_path = os.path.join(source_dir, template_path)
+
+        # Create template engine
+        template_engine = TemplateEngine(
+            template_path=template_path,
+            search_paths=[self.builder.srcdir],
+            parameter_mapping=getattr(config, "typst_template_mapping", None),
+            typst_package=getattr(config, "typst_package", None),
+            typst_template_function=getattr(config, "typst_template_function", None),
+            typst_package_imports=getattr(config, "typst_package_imports", None),
+        )
+
+        # Gather Sphinx metadata
+        sphinx_metadata = {
+            "project": config.project,
+            "author": config.author,
+            "release": config.release,
+            "copyright": config.copyright,
+        }
+
+        # Add custom elements from config
+        typst_elements = getattr(config, "typst_elements", {})
+        sphinx_metadata.update(typst_elements)
+
+        # Map parameters
+        params = template_engine.map_parameters(sphinx_metadata)
+
+        # Extract toctree options and add to parameters
+        toctree_options = template_engine.extract_toctree_options(self.document)
+        params.update(toctree_options)
+
+        # Render with template (using separate template file)
+        self.output = template_engine.render(
+            params, body, template_file="_template.typ"
+        )

typsphinx-0.3.0.dist-info/METADATA

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: typsphinx
+Version: 0.3.0
+Summary: Sphinx extension for Typst output
+Author-email: Sphinx Typst Contributors <noreply@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YuSabo90002/typsphinx
+Project-URL: Documentation, https://github.com/YuSabo90002/typsphinx#readme
+Project-URL: Repository, https://github.com/YuSabo90002/typsphinx
+Project-URL: Issues, https://github.com/YuSabo90002/typsphinx/issues
+Keywords: sphinx,typst,documentation,pdf
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sphinx>=5.0
+Requires-Dist: docutils>=0.18
+Requires-Dist: typst>=0.11.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: tox>=4.0; extra == "dev"
+Requires-Dist: tox-uv>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: sphinx-testing>=1.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: types-docutils>=0.18; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.0; extra == "docs"
+Dynamic: license-file
+
+# typsphinx
+
+[![PyPI version](https://badge.fury.io/py/typsphinx.svg)](https://badge.fury.io/py/typsphinx)
+[![Python Support](https://img.shields.io/pypi/pyversions/typsphinx.svg)](https://pypi.org/project/typsphinx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+Sphinx extension for Typst output format support.
+
+## Overview
+
+typsphinx is a Sphinx extension that enables generating Typst documents from reStructuredText sources. Typst is a modern typesetting system designed as an alternative to LaTeX, offering faster compilation and a more intuitive syntax.
+
+## Features
+
+- **Convert Sphinx documentation to Typst format**: Seamlessly transform your reStructuredText/Markdown documents
+- **Standard docutils nodes**: Full support for paragraphs, sections, lists, tables, admonitions, and more
+- **Mathematical expressions**:
+  - LaTeX syntax via mitex (`@preview/mitex:0.2.4`)
+  - Native Typst math syntax
+- **Code blocks with syntax highlighting**: Using codly package (`@preview/codly:1.3.0`)
+  - Automatic line numbering
+  - Syntax highlighting for multiple languages
+  - Highlight specific lines
+- **Images and figures**: Embed images with captions and references
+- **Cross-references and citations**: Maintain document structure with internal links
+- **Customizable templates**: Use default or custom Typst templates
+- **Direct PDF generation**: Self-contained PDF generation via typst-py (no external Typst CLI required)
+- **Multi-document support**: Generate multiple Typst files with toctree integration using `#include()`
+
+## Requirements
+
+- Python 3.9 or higher
+- Sphinx 5.0 or higher
+- typst-py 0.11.1 or higher
+
+## Installation
+
+### From PyPI (Beta Release)
+
+```bash
+pip install typsphinx
+```
+
+### Using uv (recommended for development)
+
+```bash
+# Clone the repository
+git clone https://github.com/YuSabo90002/typsphinx.git
+cd typsphinx
+
+# Install dependencies with uv
+uv sync
+
+# For development dependencies
+uv sync --extra dev
+```
+
+## Quick Start
+
+### Basic Configuration
+
+Configure Typst output in your `conf.py`:
+
+```python
+# conf.py
+
+# Note: typsphinx is auto-discovered via entry points.
+# Adding to extensions list is optional but recommended for clarity.
+# extensions = ['typsphinx']
+
+# Optional: Configure Typst builder
+typst_use_mitex = True  # Use mitex for LaTeX math (default: True)
+```
+
+### Build Typst Output
+
+```bash
+# Generate Typst files
+sphinx-build -b typst source build/typst
+
+# Generate PDF directly
+sphinx-build -b typstpdf source build/pdf
+```
+
+### Example Document
+
+Create a simple reStructuredText document:
+
+```rst
+==============
+My Document
+==============
+
+This is a paragraph with **bold** and *italic* text.
+
+Math Example
+============
+
+Inline math: :math:`E = mc^2`
+
+Block math:
+
+.. math::
+
+   \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+
+Code Example
+============
+
+.. code-block:: python
+
+   def hello_world():
+       print("Hello, Typst!")
+```
+
+This will generate a Typst file with:
+- Proper heading hierarchy
+- Formatted text with emphasis
+- LaTeX math via mitex (or native Typst math)
+- Syntax-highlighted code blocks with codly
+
+## Advanced Usage
+
+### Custom Templates
+
+Create a custom Typst template:
+
+```python
+# conf.py
+typst_template = '_templates/custom.typ'
+
+typst_elements = {
+    'papersize': 'a4',
+    'fontsize': '11pt',
+    'lang': 'ja',
+}
+```
+
+### Template Parameter Mapping
+
+Map Sphinx metadata to template parameters:
+
+```python
+# conf.py
+typst_template_mapping = {
+    'title': 'project',
+    'authors': ['author'],
+    'date': 'release',
+}
+```
+
+### Multi-Document Projects
+
+Use toctree to combine multiple documents:
+
+```rst
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   intro
+   chapter1
+   chapter2
+```
+
+This generates `#include()` directives in Typst with proper heading level adjustments.
+
+### Working with Third-Party Extensions
+
+typsphinx integrates with Sphinx's standard extension mechanism. For custom nodes from third-party extensions (e.g., sphinxcontrib-mermaid), you can register Typst handlers in your `conf.py`:
+
+```python
+# conf.py
+def setup(app):
+    # Example: Support sphinxcontrib-mermaid diagrams
+    if 'sphinxcontrib.mermaid' in app.config.extensions:
+        from sphinxcontrib.mermaid import mermaid
+        from docutils import nodes
+
+        def typst_visit_mermaid(self, node):
+            """Render Mermaid diagram as image in Typst output"""
+            # Export diagram as SVG and include in Typst
+            diagram_path = f"diagrams/{node['name']}.svg"
+            self.add_text(f'#image("{diagram_path}")\n\n')
+            raise nodes.SkipNode
+
+        # Register with Sphinx's standard API
+        app.add_node(mermaid, typst=(typst_visit_mermaid, None))
+```
+
+**How it works**:
+- typsphinx uses Sphinx's standard `app.add_node()` API (no custom registry needed)
+- Unknown nodes trigger `unknown_visit()` which logs a warning and extracts text content
+- Users can add Typst support for any extension by registering handlers in `conf.py`
+
+For more details, see the [Sphinx Extension API documentation](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_node).
+
+## Configuration Options
+
+See [docs/configuration.rst](docs/configuration.rst) for all available configuration options:
+
+- `typst_use_mitex`: Enable/disable mitex for LaTeX math
+- `typst_template`: Custom template path
+- `typst_elements`: Template parameters (paper size, fonts, etc.)
+- `typst_template_mapping`: Sphinx metadata to template parameter mapping
+- `typst_toctree_defaults`: Default toctree options
+
+## Development
+
+This project uses uv for fast package management and follows TDD (Test-Driven Development) practices.
+
+### Setup Development Environment
+
+```bash
+# Install with development dependencies
+uv sync --extra dev
+
+# Run tests (286 tests, 93% coverage)
+uv run pytest
+
+# Run tests with coverage report
+uv run pytest --cov=typsphinx --cov-report=html
+
+# Run tests across multiple Python versions
+uv run tox
+
+# Run linters
+uv run black .
+uv run ruff check .
+uv run mypy sphinxcontrib/
+```
+
+### Testing Strategy
+
+- **Unit tests**: 286 tests covering all major components
+- **Integration tests**: Full build process validation
+- **Example projects**: `examples/basic/` and `examples/advanced/`
+- **Code coverage**: 93% overall
+
+### Project Structure
+
+```
+typsphinx/
+├── sphinxcontrib/typst/    # Main package
+│   ├── builder.py          # Typst builder
+│   ├── writer.py           # Doctree writer
+│   ├── translator.py       # Node translator
+│   ├── template_engine.py  # Template processor
+│   ├── pdf.py              # PDF generation
+│   └── templates/          # Default templates
+├── tests/                  # Test suite
+├── docs/                   # Documentation
+├── examples/               # Example projects
+└── pyproject.toml          # Project configuration
+```
+
+## Known Limitations (v0.2.0)
+
+- **Bibliography**: BibTeX integration not yet supported
+- **Glossary**: Glossary generation not yet supported
+
+See full requirements verification in project documentation.
+
+## Documentation
+
+- [Installation Guide](docs/installation.rst)
+- [Usage Guide](docs/usage.rst)
+- [Configuration Reference](docs/configuration.rst)
+- [Examples](examples/)
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Write tests for new features
+4. Ensure all tests pass: `uv run pytest`
+5. Submit a pull request
+
+### Development Guidelines
+
+- Follow TDD (Test-Driven Development)
+- Maintain 80%+ code coverage
+- Use black for code formatting
+- Follow Sphinx extension conventions
+- Add tests for all new features
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built on top of [Sphinx](https://www.sphinx-doc.org/)
+- Uses [Typst](https://typst.app/) for typesetting
+- Integrates [mitex](https://github.com/mitex-rs/mitex) for LaTeX math
+- Uses [codly](https://typst.app/universe/package/codly) for code highlighting
+- Uses [gentle-clues](https://typst.app/universe/package/gentle-clues) for admonitions
+- Developed with [Claude Code](https://claude.ai/code) and Kiro-style Spec-Driven Development
+
+## Version History
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
+
+---
+
+**Status**: Stable (v0.2.2) - Production ready
+**Python**: 3.9+ | **Sphinx**: 5.0+ | **Typst**: 0.11.1+

typsphinx-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+typsphinx/__init__.py,sha256=0Ufg4ynUM70hFs7WQpxJEQ9jFh0K-QRVa19gPIJz6Vk,2011
+typsphinx/builder.py,sha256=Dk0qPp7EH8BjzOST_HgkaQqbWNi7cZD6wzQXLx_wOog,10520
+typsphinx/pdf.py,sha256=7iTjd9Pdo17dM-_29TjdD2wjQGZxDhH1DbRDV0d1xpk,5577
+typsphinx/template_engine.py,sha256=jsjOT-2vborHkp8w10d0CMMSnKa07DYFd7NdPQ1xI5I,14934
+typsphinx/translator.py,sha256=xIq7xMBHdPslFhB8KTSP2BCSu7TcDQ9764JMbe9r0UI,48497
+typsphinx/writer.py,sha256=n0M6br3Xdk_L6nsL_o06Xo83nh2iLabfbUDvWmbbb3Y,5027
+typsphinx/templates/base.typ,sha256=E6eMJzzwzY4tjJTyQUVeY6ecHj30Eg00VnX_6de6wZg,2024
+typsphinx-0.3.0.dist-info/licenses/LICENSE,sha256=hhDy2B1WzKS4HadL0kpNQO_LLJCpzAeqlmNvhdVijhk,1068
+typsphinx-0.3.0.dist-info/METADATA,sha256=BzFho6QZ94kS8ExCNli8AhBoslF-2FC8hdUFAcohGEY,10419
+typsphinx-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+typsphinx-0.3.0.dist-info/entry_points.txt,sha256=FUPwoj8Z8mx2q0v33yxTO1dlqtgbJc9FkY66rOlb01o,57
+typsphinx-0.3.0.dist-info/top_level.txt,sha256=08jmdf7hvCEFJ6UTjz8Od31dUpPK39jZJy4o73iUdyA,10
+typsphinx-0.3.0.dist-info/RECORD,,

typsphinx-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

typsphinx-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[sphinx.builders]
+typst = typsphinx
+typstpdf = typsphinx

typsphinx-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 YuSabo90002
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typsphinx-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+typsphinx