mirror of
https://github.com/adambard/learnxinyminutes-docs.git
synced 2024-12-23 17:41:41 +00:00
2df3917975
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.
2.9 KiB
2.9 KiB
| language | contributors | filename | ||||||
|---|---|---|---|---|---|---|---|---|
| restructured text (RST) |
|
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 and the docutils package.
docutils can be installed using the commandline:
$ easy_install docutils
If your system has pip, you can use it too:
$ 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:
$ 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: