Get to know reStructuredText (reST)

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 Syntax

reST has simple and easy syntax, so as for understanding. Then let’s get familiar with its functionalities:

Paragraphs

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.

Inline Markup

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.

Lists

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.

Definition List

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

Blockquotes

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.

Line Blocks

These blocks are used to give line breaks as we need.

  | These lines will be
  | broken exactly as
  | it seems

Literal Blocks

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(:)

Doctest Blocks

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

Tables

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.

Links

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.

Headings/Sections

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
---------------------

Images

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?

Footnotes

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 [1]_ and [#f1]_ also. That totally depends on user. Footnotes contains labels which are either numeric or start with #.

Comments

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.

References:

1. http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
2. http://docutils.sourceforge.net/docs/user/rst/quickstart.html
3. https://dgplug.org/irclogs/2012/rst-primer/

Conclusion

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.