Ever wondered how documentation, blogs, online books (not the PDFs) are written? Well, if it’s a really big one, RST (or reST) is the best shot.
The name reStructuredText was chosen to indicate that it is a “revised, reworked, and interpreted StructuredText”. reStructuredText is also abbreviated as RST, ReST and reST. (Wikipedia)
To convert RST to an HTML page, you’d need to install two packages namely:
and then you can use the command:
rst2html test.rst test.html
This will generate HTML page based on the RST you wrote in test.rst. Without test.html the output is just sent to the stdout.
If you don’t have rst2html command after installing the said two packages, you can try pressing the tab key to see if it is installed by some other name.
Let’s follow along with some snippets:
First the title of the doc.
====== Title ======
Here remember to keep the upper and lower lines equal, and you can skip the upper one.
Then you can write the texts and para like normal text for example:
This will come as a simple sentence. And this as another para, due to space between them.
If you don’t leave any line between two sentences, then they are joined into one.
To comment, we use
.. This is a comment
.. and the comment is required. Most of the issues that I ran into were resolved by trying to put a space or a new line while trying out RST.
A comment can be multiline in which case it’s length is determined from the indentation.
.. This is a multiline comment.
Section title can be given in a similar manner to the doc title.
Section Title ==============
# with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections ", for paragraphs
I didn’t know this so in my test.rst I tried playing to get it all correct 😛
Lists are the simplest part. Unordered list has a syntax:
* First Item * Second * And this is Third
“This text is not in the list due to the absence of ‘*’”
Ordered List can be generated manually or automatically like:
1. Some text 2. Other text more text with "other text" 1. This #. Is #. An #. Autonumbered list a. This #. Is #. Also #. Autoindexed
This is a set of text indented relative to each other. Point to note here is that, there should be a blank line just before and after the definition list.
Some term It's definition Some other term: It's definition
The options list is used to write command line tools’ option and description. This is one of my favorites too!
-a Option a -b This is b option with longer description --some This is another option
Remember to leave lines before and after starting a new body element. This was the thing I messed up most.
If you are writing about RST in RST, then what? You need literal blocks for such cases. They are not interpreted and are printed as it is.
:: This is a literal block for a in ['a', 'b', 'c', 'd']: print(a) print("some content") # A python comment
These are interactive python sessions pasted in the text. When I first tried RST, I thought these were supposed to be evaluated in Python :P. But these are for explanation purposes, to show examples, and to provide a method to test the documentation’s content using doctest modules
>>> print("This is a python command") This is a python command
The command and the output are both written by the writer.
Creating a table is another easy task though it requires some typing effort.
=== === === a b c === === === 1 2 3 3 2 1 === === ===
Another form of a table is:
+--------+--------+ |Another | form | +--------+--------+ |of |creating| +--------+--------+ |a |table | +--------+--------+
Though this is more readable, it is slightly strenuous on your fingers. But I still like this one :P.
Note: This table might appear malformed on wordpress. You can try copying it to an editor locally.
This is a normal hyperlink
`link text <https://www.duckduckgo.com>`_
This is an example of a targeted hyperlink:
`text which isn't linked currently`_ This is text apart from it .. _text which isn't linked currently: https://www.duckduckgo.com
You can also give notes in the text.
.. note:: This is a note But this isn't
You can put * around your text to put the emphasis. Generally, it italicises the content it surrounds.
To make the content bold you can use **
This text is *italicised* and this **bold**
To give more links for further reading and clarifications, you can give footnotes. They can also be autonumbered.
This is footnote one [#]_ and this two [#]_. Some text between the footnote text and links. .. [#] Hey I'm footnote one .. [#] You can refer to the official docs for more! Some text after footnote
Note that the text before and after footnote links isn’t compulsory. I just added it so that I know that it’s possible too.
This must be it.
Till the next time, don’t rest but go reST!