diff options
Diffstat (limited to 'rst.html.markdown')
| -rw-r--r-- | rst.html.markdown | 58 |
1 files changed, 33 insertions, 25 deletions
diff --git a/rst.html.markdown b/rst.html.markdown index 161a0610..56d54501 100644 --- a/rst.html.markdown +++ b/rst.html.markdown @@ -1,13 +1,14 @@ --- -language: restructured text +language: restructured text (RST) contributors: - ["DamienVGN", "https://github.com/martin-damien"] + - ["Andre Polykanine", "https://github.com/Oire"] filename: restructuredtext.rst --- -RST is 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 syntaxe (comparing to HTML). +RST is a markdown language like HTML but is much more lightweight and easier to read. ## Installation @@ -20,48 +21,55 @@ To use Restructured Text, you will have to install [Python](http://www.python.or $ easy_install docutils ``` -If your system have `pip`, you can use it too: +If your system has `pip`, you can use it too: ```bash $ pip install docutils ``` -## File syntaxe +## File syntax A simple example of the file syntax: -```rst -.. Line with two dotes 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 theire 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 --------------------- -And sub-subtitles with tilde -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 \*. -You can put text in *italic* or in **bold**, you can "mark" text as code with double backquote ``: ``print()``. +Lists are similar to Markdown, but a little more involved. -Lists are as simple as markdown: +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 - - Sub item + + - Sub item + +- Third item or * First item * Second item - * Sub item + + * Sub item + +* Third item Tables are really easy to write: @@ -72,22 +80,22 @@ France Paris Japan Tokyo =========== ======== -More complexe tabless 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 :) -Their is multiple ways to make links: +There are multiple ways to make links: -- By adding an underscore after a word : Github_ and by adding the target after the text (this have the advantage to not insert un-necessary URL inside the readed text). -- By typing a full comprehensible URL : https://github.com/ (will be automatically converted in link) -- By making a more "markdown" 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/ ``` -## How to use it +## How to Use It -RST comes with docutils in which you have `rst2html` for exemple: +RST comes with docutils where you have `rst2html`, for example: ```bash $ rst2html myfile.rst output.html @@ -95,7 +103,7 @@ $ rst2html myfile.rst output.html *Note : On some systems the command could be rst2html.py* -But their is more complexe applications that uses RST file format: +But there are more complex applications that use the RST format: - [Pelican](http://blog.getpelican.com/), a static site generator - [Sphinx](http://sphinx-doc.org/), a documentation generator |