Paragraphs contain text and may contain inline markup: emphasis,
strong emphasis, interpreted text,
Text can be organized in bullet-lists:
- This is a bullet list. - Bullets can be "*", "+", or "-". * Lists can be nested. And it is good to indent them with 4 spaces.
or in enumerated lists:
1. This is an enumerated list. 2. Tarantool build uses only arabic numbers as enumerators. #. You can put #. instead of point numbers and Sphinx will recognize it as an enumerated list.
It’s good practice to wrap lines in documentation source text.
It makes source better readable and results in lesser
The recommended limit is 80 characters per line for plain text.
In new documents, try to wrap lines by sentences, or by parts of a complex sentence. Don’t wrap formatted text if it affects rST readability and/or HTML output. However, wrapping with proper indentation shouldn’t break things.
In rST, indents play exactly the same role as in Python: they denote object boundaries and nesting.
For example, a list starts with a marker, then come some spaces and text. From there, all lines relating to that list item must be at the same indentation level. We can continue the list item by creating a second paragraph in it. To do that we have to leave it at the same level.
We can put a new object inside: another list, or a block of code. Then we have to indent 4 more spaces.
It’s best if all indents are multiples of 4 spaces, even in lists. Otherwise the document is not consistent. Also, it is much easier to put indents with tabs than manually.
Note that you have to use two or three spaces instead of one. It is allowed in rST markup:
|...|...|...|... * unordered list #. ordered list .. directive:: |...|...|...|...
|...|...|...|... #. List item 1. Paragraph continues. Second paragraph. #. List item 2. * Nested list item. .. code-block:: bash # this code block is in a nested list item * Another nested list item. |...|...|...|...
List item 1. Paragraph continues.
List item 2.
Nested list item.# this code block is in a nested list item
Another nested list item.
For code snippets, we use the
with an appropriate highlighting language.
The most commonly used highlighting languages are:
tarantoolsession—interactive Tarantool session, where command lines start with
console—interactive console session, where command lines start with
cfor programming languages.
textfor cases when we want the code block to have no highlighting.
Sphinx uses the Pygments library for highlighing source code. For a complete list of possible languages, see the list of Pygments lexers.
For example, a code snippet in Lua:
.. code-block:: lua for page in paged_iter("X", 10) do print("New Page. Number Of Tuples = " .. #page) for i=1,#page,1 do print(page[i]) end end
Lua syntax is highlighted in the output:
for page in paged_iter("X", 10) do print("New Page. Number Of Tuples = " .. #page) for i=1,#page,1 do print(page[i]) end end
To format some inline text as
code, enclose it with double
or use the
* Formatting code with backticks: ``echo "Hello world!"``. * Formatting code with a role: :code:`echo "Hello world!"`.
Both options produce the same output:
- Formatting code with backticks:
echo "Hello world!".
- Formatting code with a role:
echo "Hello world!".
If you need to highlight variables in code inline, use the
And you will get this:
Tables are very useful and rST markup offers different ways to create them.
We prefer list-tables to create table of contents:
.. container:: table .. list-table:: :widths: 25 75 :header-rows: 1 * - Name - Use
Sometimes we may need to leave comments in an rST file. To make Sphinx ignore some text during processing, use the following per-line notation with “.. //” as the comment marker:
.. // your comment here
The starting characters
.. // do not interfere with the other rST markup, and
they are easy to find both visually and using
grep. There are no characters
to escape in grep search, just go ahead with something like this:
$ grep ".. //" doc/sphinx/dev_guide/*.rst
These comments don’t work properly in nested documentation, though. For example, if you leave a comment in module -> object -> method, Sphinx ignores the comment and all nested content that follows in the method description.