Sphinx extension for fortran documentation

[jalvesz]

Project

fortran-lang

Summary

We propose the development of a Sphinx extension tailored for the Fortran community, enabling users to write and publish high-quality documentation for Fortran projects using the widely adopted Sphinx toolchain. This extension will connect Sphinx with Fortran documentation tools by leveraging the existing FORD API and, in parallel, integrating parser support from the LFortran compiler project. A proof-of-concept (fspx: https://github.com/jalvesz/fspx) demonstrates the feasibility of this approach. With support from the NumFOCUS Small Development Grant, we aim to evolve this into a robust, production-ready tool.

submitter

José Alves

project lead

@certik

Community benefit

Fortran remains a foundational language in scientific computing, yet its tooling for generating high-quality documentation lags behind more modern ecosystems. While tools like FORD provide partial solutions, they offer limited flexibility in output customization, integration, and interoperability with modern documentation systems. Our goal is to close this gap by developing a Sphinx extension and standalone Python API for Fortran documentation — building on existing work and enabling future integration with LFortran, a modern Fortran compiler developed by the fortran-lang community.

Sphinx is the standard documentation tool across the Python and scientific computing communities. This project aims to integrate Fortran projects into that ecosystem by connecting Sphinx with Fortran parsers such as FORD and LFortran, using the extension as a modular bridge layer. This approach will support mixed-language documentation workflows and improve both visibility and usability of Fortran codebases.
This work shall follow two parallel tracks in order to enable the extension to switch between backends (FORD or LFortran)

1. LFortran
   A key technical milestone will be building a lightweight, stable API that enables the translation of the internal Fortran parser as a Python tool to query structured Fortran source information. This includes:

• The list of modules, procedures (functions and subroutines), variables, parameters, and derived types with metadata (e.g., argument names, types, access specifiers), etc.

• Associations between code entities and their comments/doc-strings using pre-defined conventions (e.g., pre-line, post-line, same-line).

• The ability to expose this information as a Python-callable module or via structured JSON output. The former would be preferable.

The parser will not interpret or alter documentation comments, and it shall be agnostic to the body of procedures implementation in order to avoid strong dependencies on the compiler-toolchain. This separation of concerns allows LFortran to focus on accurate parsing and semantic analysis (with tests and guarantees around API stability), while the Sphinx extension focuses on rendering and user customization (e.g., choosing docstring styles, rendering formats, and layout).

To support diverse documentation styles, the extension will implement configurable rules for interpreting comment placement. These will include:

• Recognizing pre-line comments as documentation if no blank line is present.

• Supporting line-end comments and user-defined "sentinels" like !> or !!, but treating them as optional/customizable.

By building on LFortran’s ability to preserve comments and whitespace in the abstract syntax tree (AST), the system shall accommodate various community conventions without coupling to compiler internals.

2. FORD

While FORD is publicly available, its current licensing (GPL) is not in accordance with fortran-lang’s commitment to non-intrusive licensing politics (MIT, BSD, etc). On the other hand, FORD’s python framework already enables kickstarting the development of the extension. By enabling to use, but not strongly depending on FORD, the API shall evolve in such a way that different parsers should be pluggable. By building on top of FORD, this work will have a fast impact as many Fortran projects already use FORD as their main documentation tool. A how-to guide on how to transform the documentation using the sphinx extension shall accelerate the adoption.

Impact to the project:
With the NumFOCUS grant, the fortran-lang project will deliver a robust and extensible documentation pipeline for all Fortran practitioners. By formally integrating LFortran – which is the Fortran compiler maintained by fortran-lang – as a parser backend and specifying a clean, testable API, we establish a foundation for long-term maintainability and adaptability. The LFortran API will surface a semantic tree of modules and functions, including user-defined documentation comments — without requiring knowledge of the underlying AST or compiler logic.

Impact to the scientific ecosystem:
Fortran remains central to many scientific domains (e.g., weather modeling, computational physics), yet documentation practices are often minimal and inconsistent. This tool will enable better onboarding, improved code discoverability, and greater reproducibility — all of which are essential for modern scientific research. It also strengthens the interoperability between Fortran and Python, fostering mixed-language projects and cross-disciplinary work.

Impact to the community:
The tool will be developed within the fortran-lang community, in the open, and with support from contributors and downstream users. It will be accompanied by example projects and developer guides to encourage contributions. Its modular design (pluggable backends, flexible comment conventions, standards-aligned output) ensures that it will be adaptable to a variety of user needs and community norms.

Ultimately, this project provides a model for how compiler infrastructure and documentation tooling can cooperate cleanly, each focusing on its strengths — LFortran as a reliable source of structured code data, and the Sphinx extension as a user-facing documentation generator. The result is a powerful, sustainable tool that advances both software quality and community practice.

Deliverables include:

• A production-ready sphinx extension with support for both FORD and LFortran as pluggable backends.
• LFortran’s parser available as a Python module.
• Documentation and tutorials with examples from the fortran-lang ecosystem.
• Continuous integration and testing infrastructure.
• Detailed developer and contributor documentation to ensure long-term sustainability.

This project is backed by several community members among which: @ivan-pi @perazz @sebastian-mutz @ZedThree

Amount requested

10000

Execution plan

• Month 1: Selection of developer(s) among the community members to carry out the project (interview process)
  An estimate of $60/h rate of developer time is applied translating into 166h spread along 12 months span.

• Month 1-3:
  fspx API restructuring to obtain Sphinx compatible classes enabling switching backends

• Month 3-8:
  Implement output customization, support for cross-refences and code blocks
  Exposing the LFortran parser as a Python module for structured query

• Month 2-8:
  Testing and documentation

• Month 9:
  Ensure PiPy and conda packaging through github CI/CD for Linux, Windows and Mac
  Ensure proper hosting of the project within the fortran-lang github namespace

• Month 9-11:
  Apply the API on stdlib to showcase its use on one of Fortran-lang flag-ship projects

• Month 12:
  Public release, blog post

After completion: Practical introduction at the SAGES “Earth System Modelling and AI” workshop 2026
After completion: Presentation at the FortranCON 2026