While documenting our project, we often use Markdown syntax and save the file with .md extension. But have you ever noticed any repository which has something different? Yeah! in README file. Do you always see .md extension? Well, I first encountered with reStructuredText when I saw a repository containing .rst extension for README instead of .md. I was bit confused about what could it be, so I started searching about it and my curiosity lead me to the concept of reST. So, does it mean that Markdown and reST are same? Well, this would be like asking which flavor of lays is better. Is it Mango Salsa or Classic one(I like Classic one!)? Of course that depends on user and their use-case. So is here.
However, the main focus of Markdown is on the static web pages without much formatting and that’s where it shines. Similarly, the main focus of reST is to write documentation in a what-you-see-is-what-you-get format. But there is no such restriction, one can use any of them in any way. reST requires two python packages to get interpret. You can install them using pip as
pip install python3-docutils pip install python3-sphinx
These two packages provide rst2html utility, which can be used to convert an rst to a html file. So suppose you create a file and name it as practice.rst which would contain the reStructuredText, but it won’t be able to display the HTML on the browser. For that you would need to do something like this:
rst2html practice.rst practice.html
Now, you have the equivalent html file. It can now be used to display the content on the browser. You can convert the rst file into various formats using different utilities.
Note:- After each change in rst file, you’ll need to generate the HTML file with same process as told above.
reST has simple and easy syntax, so as for understanding. Then let’s get familiar with its functionalities:
Paragraphs are the group of text separated by one or more blank lines. All lines of same paragraph must be aligned at same indentation level.
Often we require to highlight some specific part of text. For that we use inline markups.
*I am italic* **I am bold** ``I have a code sample inside me``
They are as simple as they look. However, they have a few restrictions like they can’t be nested within one another. Also, they must be surrounded by space. For eg
These must be *surrounded* by space.
Note the spaces before and after asterisk.
We use lists in our documentations very often. So to use list, just prefix the list item with an asterisk(*). Do indent all the list item at same level. This will produce an unordered list. In order to produce an ordered list, prefix the list item with the number followed by a period. Well, there is something new here ie you can use # to autonumber the list.
* LIST ITEMS * Nested list item * Another nested list item 1. ORDERED LIST #. Autonumber list #. This item will already autonumbered.
You can use nested list as shown in above example, just make sure to give blank lines before and after the parent list element.
These are the relative indented text. One can use them to define terms and their description which can span multiple paragraphs. Just make sure to give same indentation to all the lines under the description block.
term( upto a line of text) Definition of the term, which must be indented and Can even span multiple paragraphs
They can be created by just indenting them more than the surrounding paragraphs.
This is a normal text in a paragraph This is a part of blockquote This is not part of blockquote as it is not indented at same level.
These blocks are used to give line breaks as we need.
| These lines will be | broken exactly as | it seems
The blocks are used to escape any special meaning of particular symbols. These can be created by ending a paragraph by the special symbol “::“. The whole block must be indented and separated by blank lines from surrounding text.
This is a normal text paragraph :: This is a part of literal block. All lines at this indentation level won't be processed in any way. It can span multiple paragraphs This is again part of normal text paragraph.
The marker has some special functionality. If the marker is preceded by a whitespace, the marker would get removed and if it is preceded by a non-whitespace, the marker would get replaced by a colon(:)
These are the interactive python session pasted into text. These are used to show the example pieces and do not require literal blocks syntax to be processed. These must end with a blank line.
>>> 2 + 3 5
To create a tabular structure in documentation, reST provides two ways to create tables. Simple tables are easy to create however with some restrictions ie they must contain more than one row and first column cells can’t contain multiple lines. They look something like this:
====== ======= ========= A B A and B ====== ======= ========= True True True False True False True False False False False False ====== ======= =========
However to create more complex table, we need to draw the grid structure by ourself. It might seem difficult at first but it’s not that difficult. This would look something like this:
+--------------------------+----------+----------+---------+ |Header row, column 1 | Header 2 | Header 3 | Header 4| |(Header rows are optional | | | | +==========================+==========+==========+=========+ | body row 1, column 1 | column 2 | column 3 | column 4| +--------------------------+----------+----------+---------+ | body row 2 | .. | .. | .. | +--------------------------+----------+----------+---------+
That’s it. Believe me, I have also made this by myself. The headers are separated by other fields through “=” sign. We will see about precedence of different symbols in a few moments. Keep reading.
We sometimes need to refer to links in our documentation. Using links are easy in reST.
We can use inline links like this:
`Link Text <https://www.example.com>`_
Note the underscore at the end. The links are wrapped in the backticks followed by an underscore. One can also use target link as:
This paragraph contains a `target link`_. .. _target link: https://www.example.com
Don’t forget to give the space between dots and the underscore.
Headers are created by underlining and overlining(optional) the header text by any of the punctuation character. There are few characters which can be used to mark headings. However, the following convention is generally followed as it is used in python style guide:
# with overline, for parts * with overline, for chapters =, for sections -, for subsections ^, for subsubsections ", for paragraphs
But there is no such restriction. You can use any header for your purpose, just make sure you remain consistent throughout the document. For eg
================= This is a heading ================= --------------------- This is a sub-heading ---------------------
We can insert images in our documentation through the following syntax:
.. image:: path/to/image
Again, don’t forget to give space after the periods. It’s pretty easy, isn’t it?
Including footnotes are also pretty simple in reST. Just do the following:
This is footnote 1 [#]_ and this is footnote 2 [#]_. .. [#] First footnote .. [#] Second footnote
I have used auto-numbered footnote. You can use _ and [#f1]_ also. That totally depends on user. Footnotes contains labels which are either numeric or start with #.
Comments are the important part in any language whether it is small or big. They help to understand what does the particular section do and what options can be added and where. In reST, one can give comments as:
.. This is a comment.
You can also write multi-line comments as
.. This is a multi line comment It can span along paragraphs. just make sure that there should be same; indentation level throughout the comment section. This is not a comment.
These are just few basics of reST. There is more to it. I myself don’t know much yet. Though as soon as I would learn, I’ll definitely gonna come up with another blog post for this. Till then…
Be curious and keep learning.