Documenting AbiPy

Organization of documentation

The AbiPy documentation is generated from ReStructured Text using the Sphinx documentation generation tool. The documentation sources are in the ~/docs/ directory in the repository. Major items:

  • index.rst - the top level include document for AbiPy docs

  • api - placeholders to automatically generate the api documentation

  • scripts - documentation for scripts

  • flow_gallery/gallery - automatically generated by sphinx-gallery

  • workflows - Documentation about Abinit flows/works/tasks and TaskManager

  • README.rst - the present file

  • conf.py - the sphinx configuration file

  • _static - used by the sphinx build system

The main entry point is docs/index.rst, which pulls in the files for the users guide, developers guide, api reference. The actual ReStructured Text files for the APIs of the subpackages, for the scripts and for the workflows (resp.) are kept in docs/api, docs/scripts and docs/workflows (resp.).

Additional files can be added to the various guides by including their base file name (the .rst extension is not necessary) in the table of contents. It is also possible to include other documents through the use of an include statement, such as:

.. include:: ../../TODO

The output produced by Sphinx can be configured by editing the conf.py file located in the docs/. Before building the documentation, you need to install the sphinx extensions listed in abipy/docs/requirements.txt with:

pip install -r abipy/docs/requirements.txt

To build the HTML documentation, install sphinx then type make that will execute:

sphinx-build -b html -d _build/doctrees . _build/html

Remember to issue:

export READTHEDOCS=1

before running make to activate the generation of the thumbnails in abipy/examples/flows.

The documentation is produced in _build/html. Use:

open _build/html/index.html

to open the homepage in your browser.

You can run make help to see information on all possible make targets.

Use:

./ghp_import.py _build/html/ -n -p

to deploy to gh-pages (only for project leader).

Formatting

The Sphinx website contains plenty of documentation concerning ReST markup and working with Sphinx in general. Here are a few additional things to keep in mind:

  • Please familiarize yourself with the Sphinx directives for inline markup. Abipy’s documentation makes heavy use of cross-referencing and other semantic markup. Several aliases are defined in abipy/docs/links.rst and are automatically included in each rst file via rst_epilog

  • Mathematical expressions can be rendered with mathjax in html. For example:

    :math:`\sin(x_n^2)` yields: \(\sin(x_n^2)\), and:

    .. math::

  \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}

    yields:

    \[\int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}\]

  • Bibtex citations are supported via the sphinxcontrib-bibtex extension The bibtext entries are declared in the abipy/docs/refs.bib file. For example:

    See :cite:`Gonze2016` for a brief description of recent developments in ABINIT.

    yelds: See [Gonze2016] for a brief description of recent developments in ABINIT.

    To add a new bibtex entry to the database, please use the doi2bibtex tool provided by the betterbib package:

    doi2bibtex https://doi.org/10.1103/PhysRevB.33.7017 >> refs.bib

    then change the bibtex identifier (use the name of the first author and the publication year).

  • Interactive ipython sessions can be illustrated in the documentation using the following directive:

    .. sourcecode:: ipython

  In [69]: lines = plot([1, 2, 3])

    which would yield:

    In [69]: lines = plot([1, 2, 3])

  • Use the note and warning directives, sparingly, to draw attention to important comments:

    .. note::
   Here is a note

    yields:

    Note

    here is a note

    also:

    Warning

    here is a warning

  • Use the deprecated directive when appropriate:

    .. deprecated:: 0.98
   This feature is obsolete, use something else.

    yields:

    Deprecated since version 0.98: This feature is obsolete, use something else.

  • Use the versionadded and versionchanged directives, which have similar syntax to the deprecated role:

    .. versionadded:: 0.2
   The transforms have been completely revamped.

    Added in version 0.2: The transforms have been completely revamped.

  • The autodoc extension will handle index entries for the API, but additional entries in the index need to be explicitly added.

Docstrings

In addition to the aforementioned formatting suggestions:

  • Docstrings are written following the Google Python Style Guide. We use the napoleon extension to convert Google style docstrings to reStructuredText before Sphinx attempts to parse them.

Dynamically generated figures

Figures can be automatically generated from scripts and included in the docs. It is not necessary to explicitly save the figure in the script, this will be done automatically at build time to ensure that the code that is included runs and produces the advertised figure.

Any plots specific to the documentation should be added to the examples/plot/ directory and committed to git.

sphinx-gallery