Skip to content

Latest commit

 

History

History
98 lines (83 loc) · 2.72 KB

README.md

File metadata and controls

98 lines (83 loc) · 2.72 KB
Raw

Fortran Example Project

This project is an example for:

  • Using Sphinx to document the code
  • writing Unit-tests
  • Running CI with GitLab
  • Using CMake
  • ...

Preparing a 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

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/

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
(sphinx_fortran) docs $ firefox _build/html/index.html

Activate Sphinx-Fortran in conf.py

  1. Un-comment the following lines under "Path Setup":
import os
import sys
  1. Add sphinxfortran.fortran_domain and sphinxfortran.fortran_autodoc to the extensions:
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.imgmath',
    'sphinx.ext.ifconfig',
    'sphinx.ext.intersphinx',
    'sphinxfortran.fortran_domain',
    'sphinxfortran.fortran_autodoc',
]
  1. Add the following configurations for sphinx-fortran e.g. to the end:
## FORTRAN AUTODOC
# 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