Metadata-Version: 2.4
Name: sphinx-fortran-domain
Version: 0.1.0
Summary: A modern Sphinx domain for Fortran
Author: fortran-lang community
License-Expression: MIT
Keywords: sphinx,fortran,documentation,domain
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx>=6
Provides-Extra: docs
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# Sphinx Fortran Domain

Fortran-lang's base Sphinx domain to document Fortran projects.

> **Status**: This project is preparing its first official 0.1.x release. The core API is usable and tested; feedback and issue reports are welcome.

- Changelog: [CHANGELOG.md](https://github.com/fortran-lang/sphinx-fortran-domain/blob/main/CHANGELOG.md)

## Install
For regular usage:

`pip install sphinx-fortran-domain`

For editable install for development:

`pip install -e .`

## Build the docs

Install with documentation dependencies:

`pip install -e ".[docs]"`

Build HTML documentation:

```
cd docs
make html
```

## Enable the extension

In `conf.py`:

```python
extensions = [
	"sphinx_fortran_domain",
]

# Where your Fortran sources live (directories, files, or glob patterns)
fortran_sources = [
	"../src",        # directory
	"../example/*.f90",  # glob pattern
]

# Exclude sources from parsing (directories, files, or glob patterns)
fortran_sources_exclude = [
	"../example/legacy",          # directory
	"../example/skip_this.f90",   # file
	"../example/**/generated_*.f90",  # glob
]

# Select a lexer (built-in: "regex")
fortran_lexer = "regex"

# Doc comment convention 
# Examples: '!>' or '!!' or '!@'
fortran_doc_chars = [">", "!"]
```

## Directives and roles

Manual declarations (create targets for cross-references):

```rst
.. f:function:: add_vectors(vec1, vec2)

.. f:subroutine:: normalize_vector(vec)
```

Autodoc-style views from parsed sources:

```rst
.. f:module:: example_module

.. f:submodule:: stdlib_quadrature_trapz

.. f:program:: test_program
```

Cross-references:

```rst
See :f:mod:`example_module` and :f:subr:`normalize_vector`.
```

## Writing a lexer plugin

See the full step-by-step guide in the documentation: ``docs/api/lexers.rst``.

External packages can register a lexer at import/setup time:

```python
from sphinx_fortran_domain.lexers import register_lexer

def setup(app):
	register_lexer("my-lexer", lambda: MyLexer())
```

Then use `fortran_lexer = "my-lexer"`.

## Math in doc comments

This extension parses Fortran doc comments as reStructuredText fragments, so Sphinx
roles/directives work inside docs (including math when `sphinx.ext.mathjax` is enabled).

Supported math styles:

- Recommended (reST):

```Fortran
!> .. math:: \hat{v} = \frac{\vec{v}}{|\vec{v}|}
```

Inline math also works via `:math:`:

```Fortran
!> The magnitude is :math:`|\vec{v}| = \sqrt{x^2 + y^2 + z^2}`.
```

## Community

- Contributing guide: [CONTRIBUTING.md](https://github.com/fortran-lang/sphinx-fortran-domain/blob/main/CONTRIBUTING.md)
- Code of conduct: [CODE_OF_CONDUCT.md](https://github.com/fortran-lang/sphinx-fortran-domain/blob/main/CODE_OF_CONDUCT.md)
