Top.Mail.Ru
Sphinx-build warnings reference | Tarantool
 
Contributing / Guidelines / Documentation guidelines / Sphinx-build warnings reference
Contributing / Guidelines / Documentation guidelines / Sphinx-build warnings reference

Sphinx-build warnings reference

Sphinx-build warnings reference

This document will guide you through the possible warnings raised by Sphinx engine while building the docs.

Below we cite a list with the most frequent warnings and the ways of solutions.

Similar warning: Block quote ends without a blank line; unexpected unindent

Example:

*   The last point of bullet list
This text should start after a blank line

Solution:

*   The last point of bullet list

This text should start after a blank line

This warning means that there’s a code-block with an unknown lexer. Most probably, it’s a typo. Check out the full list of Pygments lexers for the right spelling.

Example:

..  code-block:: cxx

    // some code here

Solution:

..  code-block:: cpp

    // some code here

Sometimes, however, there’s no appropriate lexer, or the code snippet can’t be lexed properly. In such case, use code-block:: text.

Example:

*   `Install <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
    ``git``, a version control system.

*   `Install <https://linuxize.com/post/how-to-unzip-files-in-linux/>`_
    the ``unzip`` utility.

Solution:

Sphinx-builder raises warnings when we call different targets the same names. Sphinx developers recommend using double underlines __ in such cases to avoid this.

*   `Install <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`__
    ``git``, a version control system.

*   `Install <https://linuxize.com/post/how-to-unzip-files-in-linux/>`__
    the ``unzip`` utility.

This warning means that you forgot to put the document name in the toctree.

Solution:

If you don’t need it there, place :orphan: directive at the top of the file. Or, if this file is included somewhere or reused, add it to the _includes directory. These directories are ignored by Sphinx because we put them in exclude_patterns in conf.py file.

Example:

This happens if you include the contents of one file with tags in another. Then Sphinx thinks the tags are repeated.

Solution:

As in previous case, don’t forget to add such file in _includes or avoid using tags within it.

Example:

This may happen when you, for example, refer to the wrong path to a document.

Solution:

Check the path.

If the path is in cartridge or another submodule, check that you’ve built the submodules content before building docs.

The reStructuredText syntax is based on indentation, much like in Python. In a block of content, all lines should be equally indented. An increase or decrease in indentation means the end of the current block and the beginning of a new one.

Example:

Note: dots show indentation spaces in these examples. For example, |..| means a two-space indentation.

|..|* (Engines) Improve dump start/stop logging. When initiating memory dump, print
how much memory is going to be dumped, expected dump rate, ETA, and the recent
write rate.

Solution:

*|...|(Engines) Improve dump start/stop logging. When initiating memory dump, print
|....|how much memory is going to be dumped, expected dump rate, ETA, and the recent
|....|write rate.

See also:

Example:

:doc:`reference/reference_lua/box_space/update`

Solution:

Sphinx did not recognise the file path correctly due to a missing slash at the beginning, so let’s just put it there:

:doc:`/reference/reference_lua/box_space/update`