Sphinx: Build the HTML output

The Sphinx documentation has the most complete information about how to configure, write, and build documentation using Sphinx. We will not duplicate that information here, but list the most relevant areas in Helpful Sphinx documentation and describe some of the specific ways we’ve implemented Sphinx at IDM.

Sphinx is a documentation tool developed by the Python community. As inputs, Sphinx takes reStructuredText (RST) or Markdown files and compiles them into a variety of output formats, such as ePub, PDF, and HTML. Sphinx can also build API reference content from the docstrings embedded in Python files.

In our implementation of Sphinx, we use RST files and docstrings as inputs to create HTML and PDF documentation (EMOD docs are available only in HTML due to the width of the parameter tables). You are likely more familiar with Markdown than RST and may ask why we’re using RST if Sphinx can ingest Markdown. For a good summary of the issues, see Eric Holscher’s blog. See reStructuredText primer for RST basics, including some of the notable differences from Markdown.

Install required software

To set your computer up to build documentation with Sphinx, you must install a handful of Python packages and Sphinx extensions. These are contained in a docs/requirements.txt file.

Note

If your package was created using the cookiecutter template (https://github.com/InstituteforDiseaseModeling/cookiecutter-python-library) then you can use tox (https://pypi.org/project/tox/) to both install the prerequisites and to locally build the html documentation. History_matching (https://github.com/InstituteforDiseaseModeling/history_matching.git) is an example package that has tox configured:

tox -e docs

  1. Create and activate a Python virtual environment. If you are working on a project with API reference generated from docstrings, you will need a separate environment for each project, but you can use the same environment for development and documentation.

  2. Navigate to the documentation folder:

    cd <project>/docs

  3. Pip install from the requirements.txt file:

    pip install -r requirements.txt

  4. If your project includes API reference generated from docstrings, install the packages you are documenting (and all of their dependencies). The process will differ from project to project; consult the README or software lead.

    Note

    If you can, we recommend that you install the packages with pip in “editable” mode. If you do this, you can make docstring changes and then rebuild the docs without needing to reinstall the packages first.

  5. (Optional) If you include mathematical equations in the documentation (EMOD does), you must have LaTeX installed locally. For more information on math markup, see the Sphinx docs on math. You can use many different distributions; the content team uses MiKTeX. Be aware that installation may take an extended amount of time.

Note

If you have pygit2 installed, you may need to uninstall it in the environment to successfully build the docs. Uninstall the pygit2 package using the following command:

pip uninstall pygit2

Build the docs

You should build the docs locally to verify your changes before submitting a pull request. If you are making substantial changes or setting up the documentation for the first time, we recommend setting up a test build on Read the Docs too. For more information, see Read the Docs: Host the docs.

Note

If your package was created using the cookiecutter template (https://github.com/InstituteforDiseaseModeling/cookiecutter-python-library) then you can use tox (https://pypi.org/project/tox/) to both install the prerequisites and to locally build the html documentation. History_matching (https://github.com/InstituteforDiseaseModeling/history_matching.git) is an example package that has tox configured:

tox -e docs

  1. Activate your virtual environment.

  2. If you modified docstrings, save your changes and re-install the package containing the docstings.

    Note

    Sphinx builds API reference content from the packages that are installed, not directly from the Python files. Therefore after making docstring changes, you must re-install packages from the local code files using setup.py or similar (not from pip) to view those changes in the docs.

  3. Navigate to the docs folder and enter:

    make html

  4. If you see warnings or errors, do the following:

    1. Locate the error and make your changes.

      Sphinx error messages will tell you on what line number the error occurs. For standalone RST files, this is the line number of the file. For errors that occur in Python docstrings, this is the line number of the individual docstring. For example, if the error is on line 32 of the file, which is the second line of the docstring for a particular method, Sphinx will indicate the method name and line 2.

      For additional help with Sphinx warnings and errors, see Sphinx build troubleshooting.

    2. If you modified docstrings, save your changes and re-install the package containing the docstrings again.

    3. To delete old build artifacts, navigate to the docs folder and enter:

      make clean

      Sphinx often won’t emit the same error/warning more than once, so sometimes errors you hit previously are hidden if artifacts aren’t deleted first.

    4. Try to build the docs again:

      make html

  5. Once the docs are building successfully, verify that the output looks as you expect. Sometimes incorrect formatting will pass build validation, but result in HTML that is not what you want. Under the _build/html folder, open the files you just updated to be sure they look the way you want.