sphinx-fortran-domain 0.0.1

A modern Sphinx domain for Fortran

Sphinx Fortran Domain

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

WARNING: This project is under construction, at this stage you can use it but expect missing features or some rendering bugs. Your friendly feedback will be very important to get this project in shape.

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:

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):

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

.. f:subroutine:: normalize_vector(vec)

Autodoc-style views from parsed sources:

.. f:module:: example_module

.. f:submodule:: stdlib_quadrature_trapz

.. f:program:: test_program

Cross-references:

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:

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):

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

Inline math also works via :math::

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