Top.Mail.Ru
Sphinx-build warnings reference | Tarantool
 

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

Пример:

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

Решение:

*   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.

Пример:

..  code-block:: cxx

    // some code here

Решение:

..  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.

Пример:

*   `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.

Решение:

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.

Решение:

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.

Пример:

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

Решение:

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

Пример:

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

Решение:

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.

Пример:

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.

Решение:

*|...|(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.

См. также:

Пример:

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

Решение:

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`