Documentation#

The documentation of GVEC is split into the following parts:

  1. User and developer documentation written in restructured text and markdown and compiled with sphinx

  2. Auto-generated fortran code documentation built with ford

Requirements#

The required python packages to build the documentation are given in docs/requirements.txt and can be installed with:

pip install -r docs/requirements.txt

In addition the graphs feature of ford requires an installation of graphviz/dot and urw-fonts.

Writing User & Developer documentation#

  • static pages (guides, examples, etc.) are written in restructured text or markdown

    • we use the myst-parser for an extended markdown supporting most sphinx directives

  • content is grouped into two subdirectories: docs/user for user documentation and doc/dev for developer documentation

    • each directory corresponds to a section in the documentation, i.e. different left sidebar for navigation

  • the third section is the auto-generated fortran api using ford

  • add all new pages to the toctree in the respective index.md

  • files & directories in docs/:

    • index.rst is the landing page and contains the main table of contents

    • conf.py contains the sphinx configuration as a python script

      • please add comments when you extend the configuration

    • Makefile contains the logic to build the sphinx documentation

    • requirements.txt contain the python packages required to build the documentation

    • templates/ contains html templates that can be used to style the documentation

    • static/ contains content that should be copied directly to the build directory

    • generators/ contains additional material that generates figures. And there is a script for generating the parameter list (generate_parameter_list.py), which parser the parameters.yaml file. This is called in conf.py to generate markdown files parameters-*.md. To add a new parameter to the yaml file, the param_dict_to_doc.ipynb has to be edited and run.

    • ford/ contains the ford configuration (ford.md) and auxiliary files

    • ford/static contains the static pages processed by ford, currently only a redirect to the main documentation is used.

    • extra/ contains auto-generated content (e.g by ford) to be included in the build directory

    • build/ is the default directory where the documentation output is saved to, e.g. within build/html/

  • you can build the documentation locally, run a manually triggered scheduled pipeline or manually run a publish/pages job

Building documentation#

The documentation is built and deployed on Read the Docs with the url https://gvec.readthedocs.io. Read the Docs allows switching between different versions. Which version are built is configured in the Read the Docs Settings. Supported versions users can switch between are configured in docs/static/version-switcher.json. Read the Docs also provides a small menu in the lower right corner that can be used to switch versions, e.g. to test a branch with a new version.

The current strategy is to provide the documentation for the latest release (the main branch) under https://gvec.readthedocs.io/main and the contents of the docs branch under the default https://gvec.readthedocs.io/latest. The docs branch should be kept up to date with develop and merged frequently, but allows us to commit directly to it, updating the documentation with minimal overhead.

FORD is configured in the docs/ford/ford.md file and can manually be triggered with:

ford docs/ford/ford.md

This will generate files in docs/extra/ford.

The sphinx documentation is configured in docs/conf.py and docs/Makefile and build with

cd docs
make cleanall
make html

generating documentation in docs/build. It will copy files from docs/static and docs/extra. If your webbrowser cannot render the html and css files in docs/build/html/ properly, you can start a local webserver with python -m http.server

Internals#

The FORD_PREFIX environment variable is used to set a path prefix to the absolute path used to link to the ford documentation in the header. By default this is /ford/index.html, but on GitLab we need to link to /gvec/ford/index.html.