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.
Similar warning: Unknown target name: «…»
Check the target spelling and the tag syntax.
Пример:
.. _box_space-index_func
See the :ref:`Creating a functional index <box_space-index_func>` section.
Решение:
A semicolon is missing in the tag definition:
.. _box_space-index_func:
Warning example: Anonymous hyperlink mismatch: 1 references but 0 targets.
Check the hyperlink formatting.
Пример:
Read more in `Lua Manual <https://www.lua.org/manual/5.3`__.
Решение:
A closing greater-than sign is missing in the tag definition:
Read more in `Lua Manual <https://www.lua.org/manual/5.3>`__.
Пример:
This may happen when you refer to a wrong path to a document.
Решение:
Check the path.
If the path points to a submodule, check that you’ve built the submodules content before building docs.
Пример:
Read more in :ref:`<sql_data_type_conversion>`.
Решение:
We recommend using custom captions with :ref::
Read more in :ref:`Data Type Conversion <sql_data_type_conversion>`.
См. также:
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.
См. также: