diff options
Diffstat (limited to 'rst.html.markdown')
| -rw-r--r-- | rst.html.markdown | 26 |
1 files changed, 14 insertions, 12 deletions
diff --git a/rst.html.markdown b/rst.html.markdown index 2423622e..c68c1d54 100644 --- a/rst.html.markdown +++ b/rst.html.markdown @@ -6,9 +6,9 @@ contributors: filename: restructuredtext.rst --- -RST is a file format formely created by Python community to write documentation (and so, is part of Docutils). +RST, Restructured Text, is a file format created by the Python community to write documentation. It is part of [Docutils](https://docutils.sourceforge.io/rst.html). -RST files are simple text files with lightweight syntax (comparing to HTML). +RST is a markup language like HTML but is much more lightweight and easier to read. ## Installation @@ -33,25 +33,27 @@ $ pip install docutils A simple example of the file syntax: ``` -.. Lines starting with two dots are special commands. But if no command can be found, the line is considered as a comment +.. Lines starting with two dots are special commands. But if no command can be found, the line is considered as a comment. ========================================================= Main titles are written using equals signs over and under ========================================================= -Note that there must be as many equals signs as title characters. +Note that each character, including spaces, needs an equals sign above and below. -Title are underlined with equals signs too -========================================== +Titles also use equals signs but are only underneath +==================================================== Subtitles with dashes --------------------- You can put text in *italic* or in **bold**, you can "mark" text as code with double backquote ``print()``. +Special characters can be escaped using a backslash, e.g. \\ or \*. + Lists are similar to Markdown, but a little more involved. -Remember 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: +Remember 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: - First item - Second item @@ -78,15 +80,15 @@ France Paris Japan Tokyo =========== ======== -More complex tables can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this :) +More complex tables can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this. :) There are multiple ways to make links: -- By adding an underscore after a word : Github_ and by adding the target URL after the text (this way has the advantage to not insert unnecessary URLs inside readable text). -- By typing a full comprehensible URL : https://github.com/ (will be automatically converted to a link) -- By making a more Markdown-like link: `Github <https://github.com/>`_ . +- 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). +- By typing a full comprehensible URL : https://github.com/ (will be automatically converted to a link). +- By making a more Markdown-like link: `GitHub <https://github.com/>`_ . -.. _Github https://github.com/ +.. _GitHub: https://github.com/ ``` |