Using Sphinx Fortran¶

Installing Sphinx¶

General:¶

use Python 2.7.x
install sphinx
install sphinx-fortran
optional: install sphinx_rtd_theme
Create directory ${MY_FORTRAN_PROJECT}/doc and change into it.
Run sphinx-quickstart

In an Anaconda Python Environment:¶

As Sphinx-Fortran at this point doesn’t support Python 3, we start off with a Python-2 based conda environment:

$ conda create -n sphinx_fortran python=2
Fetching package metadata ...........
[...]
# To activate this environment, use:
# > source activate sphinx_fortran
#
# To deactivate an active environment, use:
# > source deactivate

$ source activate sphinx_fortran
(sphinx_fortran)$ conda install sphinx sphinx_rtd_theme

# The latest release of sphinx-fortran on PyPi does not work with
# Sphinx 1.6b1 or newer.
# (sphinx_fortran)$ pip install sphinx-fortran
# Install master from GitHub instead:
(sphinx_fortran)$ git clone https://github.com/VACUMM/sphinx-fortran.git
(sphinx_fortran)$ cd sphinx-fortran
(sphinx_fortran)$ python setup.py install

Configure Sphinx and Sphinx-Fortran¶

Generating the initial Project¶

$ mkdir Example_Fortran
$ cd Example_Fortran
$ mkdir src
$ wget https://acenet-arc.github.io/ACENET_Summer_School_General/code/profiling/md_gprof.f90
$ mv  md_gprof.f90  src/md.f90

Generating the initial Sphinx Documentation¶

(sphinx_fortran) Example_Fortran $ echo '**/_build/'  >> .gitignore
(sphinx_fortran) Example_Fortran $ mkdir docs
(sphinx_fortran) Example_Fortran $ cd docs
(sphinx_fortran) docs $ sphinx-quickstart
# leaving all values at their default except for:
> Project name: Example Fortran Project
> Author name(s): John Doe

(sphinx_fortran) docs $ make html
# open the HTML documentation in Firefox:
(sphinx_fortran) docs $ firefox _build/html/index.html

Enable Sphinx-Fortran¶

Un-comment the following lines under “Path Setup”:
```
import os
import sys
```
Add sphinx.ext.autodoc, sphinxfortran.fortran_domain and sphinxfortran.fortran_autodoc to the list of extensions in conf.py:
```
extensions = [
    # [...]
    'sphinx.ext.autodoc',
    'sphinxfortran.fortran_domain',
    'sphinxfortran.fortran_autodoc',
]
```
Some other extensions like sphinx.ext.imgmath or sphinx.ext.todo might be useful as well.
Set the html_theme to something nicer than the default, e.g. bizstyle, classic or sphinxdoc or sphinx_rtd_theme :
```
html_theme = 'sphinx_rtd_theme'
```

Add the following configuration to the end of conf.py:

## -- Options for Sphinx-Fortran ---------------------------------------------
# List of possible extensions in the case of a directory listing
fortran_ext = ['f90', 'F90', 'f95', 'F95']

# This variable must be set with file pattern, like "*.f90", or a list of them. 
# It is also possible to specify a directory name; in this case, all files than 
# have an extension matching those define by the config variable `fortran_ext` 
# are used.
fortran_src = [ os.path.abspath('../src/'),  ]

# Indentation string or length (default 4). If it is an integer, 
# indicates the number of spaces.
fortran_indent = 4

Optional: Enable Inter-Sphinx¶

The intersphinx extension allows linking to pages of other sphinx-based documentation. Here we enable the extension and then create references to the documentation of the Sphinx project itself and the sphinxfortran extension.

extensions = [
    'sphinx.ext.intersphinx',
    # [...]
]

## -- Options for Inter-Sphinx---- -------------------------------------------
intersphinx_mapping = {
   'python':         ('https://docs.python.org/3', None)
   'sphinx':         ('http://www.sphinx-doc.org/en/stable', None),
   'sphinxfortran':  ('http://sphinx-fortran.readthedocs.io/en/latest/', None),
}

Now we can include a link to the documentation of Intersphinx by including :py:mod:`Intersphinx<sphinx:sphinx.ext.intersphinx>` in this .rst file. Refer to Cross-referencing syntax and Intersphinx Documentation on how to use it.

Create API section¶

Add the following lines to the index.rst file:
```
API
===
.. toctree::
   :maxdepth: 1

   md_all
```
The entry md_gprof_all adds a link to the file md_gprof_all.rst to the API index.
Create md_all.rst with the following content:
1 2 3 4 5 6 7 8
.. _md_program: MD Program ========== This is a simple Molecular Dynamics program. .. f:autosrcfile:: md.f90
This file contains the following directives:
- The reference label .. _md_program: can be used to link to the section header by using :ref:`md_program` in a .rst file. E.g. see MD Program.
- The line:
  - .. f:autosrcfile:: md.f90
  will include the autodoc for these Fortran files in this document. If appropriate header-comments and inline-comments have been added to the Fortran code, these will be added to the API description of the elements included in those files.
Create more API pages with Autodocs. For projects consisting of many source files, it good to organize them a bit. Pages can also be organized hierarchically by adding a .. toctree:: to a page and define sub-pages. See the TOC tree reference in the Sphinx docs.

Create Pages For User Manual¶

Apart from API documentation, User-Manual pages can be written and added to the toctree in index.rst (Just as this page).
These pages can be organized hierarchically as well, by adding a .. toctree:: to a page and define sub-pages. See the TOC tree reference in the Sphinx docs.