FAQ#

If you still have questions after consulting the information here or notice information that is out of date or incomplete in some way, file a ticket in the doc-guidance repository so we can update the guidance.

I got an email that the Read the Docs build broke, but I can’t see the build logs#

The Read the Docs builds are configured to email someone from the documentation team and the repository owner when the documentation build fails. However, you must request a Read the Docs member account from the ITOps team to view the build logs that the email links to. An admin account is required to configure the build itself.

Sphinx says my doc build succeeded, but the _build/html folder is empty#

Sometimes, if you do the initial installation of the Python package being documented and the documentation build in the same command prompt window, you will encounter this problem. Close the command prompt window and open a new one, re-running make html.

I’m testing my Sphinx build locally, but it hits the first warning/error and then stops#

The Sphinx builds are configured to treat warnings as errors because the build is overly permissive and treats certain unacceptable outcomes, such as completely empty topics or broken links, as only warnings. Therefore, any warning or error will be treated as an error and stop the build process. However, you can temporarily turn off this setting so that you can view all warnings found during the build process to facilitate troubleshooting.

  1. Depending on your OS, open the make.bat file (Windows) or Makefile (Linux).

  2. In SPHINXOPTS, remove the “-W” setting.

  3. Run “make html” and edit your files as necessary to eliminate all warnings or errors.

  4. Before committing your changes, add the “-W” setting again.

These Sphinx error messages don’t make any sense to me! Help!#

reStructuredText (RST) relies heavily on indentation to convey semantic meaning, which differs from other markup languages like HTML or XML that use opening and closing tags. When you make an indentation mistake, Sphinx will try to guess what format you are attempting: bulleted list, embedded code, table, etc. and indicate this in the error message. It doesn’t always guess correctly and can’t rely on opening/closing tags.

If you see an error that references a type of list, the problem is almost certainly incorrect indentation. Most often, these are due to having bulleted, numbered, or definition lists with multiple paragraphs, code samples, or nested lists. These nested elements must be aligned correctly. For more information on formatting lists, see the Sphinx docs on RST basics and lists.

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 more troubleshooting help, see Sphinx build troubleshooting.

“Pandoc wasn’t found” error building docs locally (make html)#

You may encounter this error when attempting to build documentation locally, make html, when the requirements.txt file in the /docs folder includes the pandoc package.

The resolution is to either install pandoc using apt get pandoc and then pip install pandoc or to use conda (https://anaconda.org/anaconda/conda). For more details, see: https://stackoverflow.com/questions/62398231/building-docs-fails-due-to-missing-pandoc