learnxinyminutes-docs/rst.html.markdown
Isaac Virshup 2df3917975
[RST/en] Fix compile errors from link and escaping
There were two issues here:

* The non-inline link was used incorrectly, and should have a colon after the specifier. 
* A compile error was generated from having a non-escaped `*`.

These can be verified by running `rst2html`:

```sh
$ rst2html.py ./restructuredtext.rst tmp.html
./restructuredtext.rst:24: (WARNING/2) Inline emphasis start-string without end-string.
./restructuredtext.rst:59: (WARNING/2) malformed hyperlink target.
```

After adding the colon, and adding the escape

```sh
$ rst2html.py ./restructuredtext.rst tmp.html
$
```

I've also added a sentence on escaping.
2020-06-24 16:55:02 +10:00

116 lines
2.9 KiB
Markdown

---
language: restructured text (RST)
contributors:
- ["DamienVGN", "https://github.com/martin-damien"]
- ["Andre Polykanine", "https://github.com/Oire"]
filename: restructuredtext.rst
---
RST is a file format formely created by Python community to write documentation (and so, is part of Docutils).
RST files are simple text files with lightweight syntax (comparing to HTML).
## 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
```
If your system has `pip`, you can use it too:
```bash
$ pip install docutils
```
## File syntax
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
=========================================================
Main titles are written using equals signs over and under
=========================================================
Note that there must be as many equals signs as title characters.
Title are underlined with equals signs too
==========================================
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:
- First item
- Second item
- Sub item
- Third item
or
* First item
* Second item
* Sub item
* Third item
Tables are really easy to write:
=========== ========
Country Capital
=========== ========
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 :)
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/>`_ .
.. _Github: https://github.com/
```
## How to Use It
RST comes with docutils where you have `rst2html`, for example:
```bash
$ 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:
- [Pelican](http://blog.getpelican.com/), a static site generator
- [Sphinx](http://sphinx-doc.org/), a documentation generator
- and many others
## Readings
- [Official quick reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html)