Zen

Source string Source string

85/10000 · 85
English Actions
Basic syntax
Paragraphs contain text and may contain inline markup: *emphasis*, **strong emphasis**, `interpreted text`, ``inline literals``.
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.
Wrapping text
It's good practice to wrap lines in documentation source text. It makes source better readable and results in lesser ``git diff``'s. 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.
Indentation
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::
|...|...|...|...
Example:
|...|...|...|...
#. 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.
|...|...|...|...
Resulting output:
List item 1. Paragraph continues.
Second paragraph.
List item 2.
Nested list item.
# this code block is in a nested list item
Another nested list item.
Making comments
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``. To find comments in source files, go ahead with something like this:
$ grep -n "\.\. //" doc/reference/**/*.rst
doc/reference/reference_lua/box.rst:47:.. // moved to "User Guide > 5. Server administration":
doc/reference/reference_lua/box.rst:48:.. // /book/box/triggers
...
If you're working with PyCharm or other similar IDE, links in the console will be clickable and will lead right to the source file and string. Check it out!

Loading…

User avatar None

New source string

testing_project / Documentation: contributing/docs/markup/intro — English

|...|...|...|...
* unordered list
#. ordered list
.. directive::
|...|...|...|...
a year ago
Browse all string changes

Things to check

Ellipsis

The string uses three dots (...) instead of an ellipsis character (…)

Reset

Glossary

English English
No related strings found in the glossary.

String information

Flags
read-only
String age
a year ago
Last updated
a year ago
Source string age
a year ago
Translation file
string 17