Documentation

The SDF documentation is built using Sphinx. This page is not a Sphinx tutorial. To get familiar with Sphinx, consult the documentation of Sphinx itself, or some other tutorial. This page only addresses some Sphinx extensions and tools used to generate the SDF documentation.

To build the documentation locally, use the Makefile in the docs directory.

Hosting

The documentation is currently hosted using GitLab Pages. The CI Pipeline of the SDF source repository runs the tests, an on completion, it triggers a downstream job in the Pages repository.

sphinx.ext.doctest

The doctest extension integrates the doctest tool from the Python standard library. Running the doctest builder (sphinx-build -b doctest ...) searches for doctest directives in the documentation and executes them as test cases.

.. doctest::

    >>> print("Hello World!")
    Hello World!

sphinx-apidoc

The sphinx-apidoc tool automatically generates sphinx sources for the sphinx.ext.autodoc extension.

Running sphinx-apidoc -o _apidoc ../SDF ../SDF/extern generates sphinx sources for the SDF module (in the ../SDF directory) , excluding the SDF.extern submodule, in the _apidoc directory.

sphinx.ext.intersphinx

While directives like :py:func allow references to internally documented Python objects, the intersphinx extension enables us to refer to other modules like the Python standard library or Numpy.