typsphinx 0.3.0__tar.gz

typsphinx-0.3.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,310 @@
+# 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+