Getting started with sphinx-ford

Getting started with sphinx-ford#

In this tutorial we install sphinx-ford, write a small module page, and build HTML output. The result is a clean baseline project with working directives and cross-references.

Installing sphinx-ford#

We start by installing the package:

pip install sphinx-ford

Note

We do not need FORD installed for this tutorial, the Fortran domain works entirely on its own. We will use FORD’s auto-documentation bridge in the next tutorial.

Setting up the project#

We create a minimal Sphinx project. If we already have one, we skip to the next section:

mkdir fortran-docs && cd fortran-docs
sphinx-quickstart --quiet --project "My Fortran Docs" --author "me"

Now we enable sphinx-ford by adding it to conf.py:

extensions = ["sphinx_ford"]

Writing our first module#

We open index.rst (or index.md for MyST) and replace its contents with:

reStructuredText

My Fortran Library
==================

.. f:module:: physics
   :permission: public

   Physical constants and utility routines.

   .. f:variable:: speed_of_light
      :parameter:

      Speed of light in vacuum (m/s).

   .. f:function:: kinetic_energy(mass, velocity)

      Compute kinetic energy.

      :param mass: Object mass
      :ftype mass: real(dp)
      :intent mass: in
      :param velocity: Object velocity
      :ftype velocity: real(dp)
      :intent velocity: in
      :rtype: real(dp)

MyST

# My Fortran Library

````{f:module} physics
:permission: public

Physical constants and utility routines.

```{f:variable} speed_of_light
:parameter:

Speed of light in vacuum (m/s).
```

```{f:function} kinetic_energy(mass, velocity)

:param mass: Object mass
:ftype mass: real(dp)
:intent mass: in
:param velocity: Object velocity
:ftype velocity: real(dp)
:intent velocity: in
:rtype: real(dp)
```
````

Building and viewing the result#

We run the Sphinx build:

sphinx-build . _build/html

We open _build/html/index.html in a browser. We should see:

A module physics heading with the description we wrote.
A parameter speed_of_light entry (because we used :parameter:).
A function kinetic_energy(mass, velocity) with typed parameters.

This renders as:

module physics#

Physical constants and utility routines.

parameter speed_of_light#

Speed of light in vacuum (m/s).

function kinetic_energy(mass, velocity)#

Compute kinetic energy.

Parameters:

mass (real(dp)) – Object mass

velocity (real(dp)) – Object velocity

Intent:

mass – in

velocity – in

Rtype:

real(dp)

Adding cross-references#

We add a second module that references the first. We append to our file:

reStructuredText

.. f:module:: simulation

   Simulation routines. Uses :f:mod:`physics`.

   .. f:subroutine:: run(dt)

      Run a simulation step using :f:func:`physics.kinetic_energy`.

MyST

```{f:module} simulation

Simulation routines. Uses {f:mod}`physics`.

```{f:subroutine} run(dt)

Run a simulation step using {f:func}`physics.kinetic_energy`.
```
```

We rebuild and notice that physics and physics.kinetic_energy are now clickable links pointing back to their definitions above.

This renders as:

module simulation#

Simulation routines. Uses physics.

subroutine run(dt)#

Run a simulation step using physics.kinetic_energy.

What we have created#

We now have a Sphinx site that documents Fortran code with:

Modules, functions, variables and types as first-class entities
Automatic cross-referencing between entities
Module, procedure and type indices (see the sidebar)

Next, we can connect FORD to auto-generate documentation from Fortran source files, or explore the reference for all available directives.