Top.Mail.Ru
Sphinx-build warnings reference | Tarantool
Tarantool
Узнайте содержание релиза 2.8

Sphinx-build warnings reference

This document will guide you through the warnings that can be raised by Sphinx while building the docs.

Below are the most frequent warnings and the ways to solve them.

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

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

Пример:

*   `Install <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
    ``git``, the 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 name. 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``, the 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 want to include the document in a toctree, place the :orphan: directive at the top of the file. If this file is already included somewhere or reused, add it to the _includes directory. Sphinx ignores everything in this directory because we list it among exclude_patterns in conf.py.

This happens if you include the contents of a file into another file, when the included file has tags in it. In this, Sphinx thinks the tags are repeated.

Решение:

As in the previous case, add the file to _includes or avoid using tags in it.

Пример:

This may happen when you refer to a wrong path to a document.

Решение:

Check the path.

If the path points to 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. All lines in a block of content must be equally indented. An increase or decrease in indentation denotes the end of the current block and the beginning of a new one.

Пример:

Note: In the following examples, dots stand for indentation spaces. For example, |..| denotes a two-space indentation.

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

См. также:

Пример:

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

Решение:

Sphinx did not recognize 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`