RST, Restructured Text, is a file format created by the Python community to write documentation. It is part of Docutils.
RST is a markup language like HTML but is much more lightweight and easier to read.
Installation ¶
To use Restructured Text, you will have to install Python and the docutils package.
docutils can be installed using the commandline:
1$ easy_install docutils
If your system has pip, you can use it too:
1$ pip install docutils
File syntax ¶
A simple example of the file syntax:
1.. Lines starting with two dots are special commands. But if no command can be found, the line is considered as a comment.
2
3=========================================================
4Main titles are written using equals signs over and under
5=========================================================
6
7Note that each character, including spaces, needs an equals sign above and below.
8
9Titles also use equals signs but are only underneath
10====================================================
11
12Subtitles with dashes
13---------------------
14
15You can put text in *italic* or in **bold**, you can "mark" text as code with double backquote ``print()``.
16
17Special characters can be escaped using a backslash, e.g. \\ or \*.
18
19Lists are similar to Markdown, but a little more involved.
20
21Remember to line up list symbols (like - or \*) with the left edge of the previous text block, and remember to use blank lines to separate new lists from parent lists:
22
23- First item
24- Second item
25
26 - Sub item
27
28- Third item
29
30or
31
32* First item
33* Second item
34
35 * Sub item
36
37* Third item
38
39Tables are really easy to write:
40
41=========== ========
42Country Capital
43=========== ========
44France Paris
45Japan Tokyo
46=========== ========
47
48More complex tables can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this. :)
49
50There are multiple ways to make links:
51
52- By adding an underscore after a word : GitHub_ and by adding the target URL after the text (this way has the advantage of not inserting unnecessary URLs in the visible text).
53- By typing a full comprehensible URL : https://github.com/ (will be automatically converted to a link).
54- By making a more Markdown-like link: `GitHub <https://github.com/>`_ .
55
56.. _GitHub: https://github.com/
How to Use It ¶
RST comes with docutils where you have rst2html, for example:
1$ rst2html myfile.rst output.html
Note : On some systems the command could be rst2html.py
But there are more complex applications that use the RST format: