Sphinx build troubleshooting#

Sphinx catches many problems by issuing errors and warnings. Warnings are treated as errors (in other words, they cause the build to fail) in our build configuration because warnings are overly permissive of significant problems. When troubleshooting, it can be helpful to temporarily turn off this setting so the build doesn’t stop on the first warning. See I’m testing my Sphinx build locally, but it hits the first warning/error and then stops.

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.

However, Sphinx is not perfect and there are some types of issues that are more likely to be missed. Therefore, it is important to view the HTML output to verify that it built as intended. It’s common to build without warning and still see problems in the following areas, so review carefully!

Note

TL;DR: When in doubt, check your indentation (spaces not tabs) and add blank lines between different elements in a list. Consult the Sphinx docs for a complete reference.

Bulleted/numbered/definition lists #

If the indentation is wrong (especially if you have multiple levels of indentation for nested lists), you may see text formatted incorrectly. For example, the numbering or nesting of items may be off or entire lines my be in bold.
If the list includes multiple paragraphs per item or code, you may need to include blank lines between each element.
See lists and quote-like blocks for more examples.

Code formatted text, especially within lists #

Code formatted text requires a code-block directive (or a double colon for Python code), a blank line, then indented text. This is the most common and simplest syntax:
```
Introductory sentence::

    Indented Python code

Plain text.
```
If the indention is off, you may see plain text instead of code.

If code appears in a list, remember that the code must be indented more than the plain text in the list item it belongs to. For example, this example shows a JSON sample in a bulleted list:

*   This is plain text in a list item.

    .. code-block:: json

        {
            "Indented": "Code block"
        }

*   This is plain text in a second list item.

Docstrings #

The most common problems occur when multi-line definitions are not indented properly or when you want to include a code sample in the definition.

The parameter list in Python docstrings is formatted very similar to a definition list. Remember to introduce code snippets with a double colon, indent the code sample, and include a blank line before and after the code. For example:

Introductory paragraph describing the function.

Args:
    parameter1: This is a short definition.
    parameter2: This is a longer definition. I need to include so much
        information that it needs a second line. Notice the indentation.
    parameter3: This is a definition that needs a code example to
        make the information more clear. Do that like so::

            def function_name():
                print('Tada!')

    parameter4: This is the parameter following the sample code. Notice
        the indentation and preceding blank line.

Internal links to arbitrary references, figures, or API elements #

Sphinx has special formatting for all of these types of internal links. The Sphinx build will automatically use the title of these elements as the link text. See cross-referencing syntax.
Do not use “see XYZ figure” in plain text because there will be no notification if the title of the figure changes and this reference is incorrect.

External links #

By default, Sphinx does not verify that external links are live and accurate, only that they are correctly formatted as URLs. Run make linkcheck to test the links.

Bold or italicized text #

Sphinx checks that there are closing and opening tags for bold (**) and italics (*).
If you forget a tag in text that includes a lot of such formatting you may end up with entire sentences in bold or italics.

CSV tables #

If you forget to enclose text that contains a comma in quote marks, you may see blank table cells or additional columns/rows.

Text around a Sphinx directive #

Python and Sphinx are very strict about indentation, so when you have multiple directives (code within lists, multi-level lists, notes, etc.) you need to be extra careful.

Warnings, notes #

When adding notes, remember that there are Sphinx directives that will format warnings and notes to be more noticeable. For example:
```
.. warning::

    This is a warning!
```