2016-06-26 16:34:16 +03:00
---
language: restructured text
contributors:
- ["DamienVGN", "https://github.com/martin-damien"]
2017-01-14 00:54:30 +03:00
- ["Andre Polykanine", "https://github.com/Oire"]
2016-06-26 16:34:16 +03:00
filename: restructuredtext.rst
---
2017-01-07 00:02:45 +03:00
RST is a file format formely created by Python community to write documentation (and so, is part of Docutils).
2016-06-26 16:34:16 +03:00
2017-01-07 00:02:45 +03:00
RST files are simple text files with lightweight syntax (comparing to HTML).
2016-06-26 16:34:16 +03:00
## Installation
To use Restructured Text, you will have to install [Python ](http://www.python.org ) and the `docutils` package.
`docutils` can be installed using the commandline:
```bash
$ easy_install docutils
```
2017-01-07 00:02:45 +03:00
If your system has `pip` , you can use it too:
2016-06-26 16:34:16 +03:00
```bash
$ pip install docutils
```
2017-01-07 00:02:45 +03:00
## File syntax
2016-06-26 16:34:16 +03:00
A simple example of the file syntax:
```rst
2017-01-07 00:02:45 +03:00
.. Lines starting with two dots are special commands. But if no command can be found, the line is considered as a comment
2016-06-26 16:34:16 +03:00
=========================================================
Main titles are written using equals signs over and under
=========================================================
2017-01-07 00:02:45 +03:00
Note that there must be as many equals signs as title characters.
2016-06-26 16:34:16 +03:00
Title are underlined with equals signs too
==========================================
Subtitles with dashes
---------------------
2017-01-07 00:02:45 +03:00
And sub-subtitles with tildes
2016-06-26 16:34:16 +03:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can put text in *italic* or in **bold** , you can "mark" text as code with double backquote ``: ``print()``.
2017-01-07 00:02:45 +03:00
Lists are as simple as in Markdown:
2016-06-26 16:34:16 +03:00
- First item
- Second item
- Sub item
or
* First item
* Second item
* Sub item
Tables are really easy to write:
=========== ========
Country Capital
=========== ========
France Paris
Japan Tokyo
=========== ========
2017-01-07 00:02:45 +03:00
More complex tabless can be done easily (merged columns and/or rows) but I suggest you to read the complete doc for this :)
2016-06-26 16:34:16 +03:00
2017-01-07 00:02:45 +03:00
There are multiple ways to make links:
2016-06-26 16:34:16 +03:00
2017-01-07 00:02:45 +03:00
- 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/>` _ .
2016-06-26 16:34:16 +03:00
.. _Github https://github.com/
```
2017-01-07 00:02:45 +03:00
## How to Use It
2016-06-26 16:34:16 +03:00
2017-01-07 00:02:45 +03:00
RST comes with docutils where you have `rst2html` , for example:
2016-06-26 16:34:16 +03:00
```bash
$ rst2html myfile.rst output.html
```
*Note : On some systems the command could be rst2html.py*
2017-01-07 00:02:45 +03:00
But there are more complex applications that use the RST format:
2016-06-26 16:34:16 +03:00
- [Pelican ](http://blog.getpelican.com/ ), a static site generator
- [Sphinx ](http://sphinx-doc.org/ ), a documentation generator
- and many others
2017-01-14 00:54:30 +03:00
## Readings
2016-06-26 16:34:16 +03:00
- [Official quick reference ](http://docutils.sourceforge.net/docs/user/rst/quickref.html )