Intro to reStructuredText

Hello readers! Yesterday, in dgplug summer training, we had a session in which we were introduced to reStructuredText. I had been aware of and used Markdown before but it was my first time that I put my hands on reStruncturedText and seen how it works. Let’s go through a quick intro to this simple yet efficient tool.

What is reStructuredText?

It is simply a plaintext easy-to-read markup language, also abbreviated as reST.

It is part of the Docutils project and was developed by David Goodger and initially released on April 2, 2002 (source Wikipedia).

reST files have the extension .rst.

Why reStructuredText?

Ever want to get rid of those HTML tags while creating a simple webpage? Ever want to see an alternative of your Readme file format other than Markdown? Ever want to try out an efficient tool using which you may document programs especially of Python? Or say you want to create any standalone document like the changelog for your FOSS project. Then reStructuredText is the tool that fits in your purpose.

I read from Wikipedia that reStructuredText has been a core component of Python’s Sphinx document generation system since 2008.

And if you’ll look at the official documentation of reStructuredText you’ll find this module –> statemachine.py, It is completely documented using reST. Isn’t it awesome?

A quick hands-on with step by step examples

In the session, we were introduced with reST with this Primer, a big thanks to our mentor Kushal.

The first step is to install these tools

• python3-docutils
• python3-sphinx

Now create any file (say doc.rst) and let’s try out the following examples.

Document Title

Open the file and create a title with:

=======
A Title
=======

Save and exit

Display your reST file as HTML

On your shell give command   –>   $ rst2html doc.rst doc.html
This will convert your reST to HTML.

and open doc.html to see your reST in a form of a webpage.

Every time you’ll make changes to your doc.rst you’ll have to first convert that to HTML to see the webpage with updated changes.

Section Title

This is a section title
=======================

Sub-section

This is a sub section
---------------------

Note: You may use any of these character for section title and sub-section   = – ` : . ‘ ” ~ ^ _ * + #   but, the character you’ll use for the first “section title” it will get fixed to it. Means, if you use that character again, then it can only be used for a section title. Similarly the character you’ll use for the first “sub-section” it will get fixed to it as well. Don’t interchange the usage of these characters. If you have chosen a character for section-title let it be constant for all the section-titles otherwise you are likely to get an error while converting this .rst to .html.

Basic Inline markup

This is how to *emphasize* a word.
This is how to **strong emphsize** a word.
And this is a standalone hyperlink  https://google.com

Paragraphs and Indentation

This is paragraph number 1.

     This is paragraph number 2. With indentation.

Note: Multiple separate lines are counted as a single separate line.

Lists

Unordered/bullet list

- object 1
- object 2

Ordered/enumerated list

1. object 1
2. object 2

Definition list

Term 1: optional_classifier
       This is definition 1.

Option list

-a          purpose of attribute 'a'
-out        purpose of attrubute 'out'

Field list

:Student: Name of student
:Enroll: Student's enrollment number

Blocks

Literal block

::
       This is a literal block.
             Where no foramtting takes place.
       Useful for code samples.
       It will continue until indentation is close

This is outside literal block.

Line block

| this is a
| line block
| useful for
| writing addresses

Quote block

These are simply:

       indented paragraphs

Doctest block

Doctest blocks are interactive Python sessions.
They begin with: >>>like >>> print "This is a doctest block." This is a doctest block.

Comments

.. This is a comment.
    Will continue till
    indentation is completely over or

   if an empty line is introduced. This is outside of the comment

This is outside of the comment

Links

Titled link

This is `title <link>`_

Targetted link

`The Geeky Way`_ is a technical blog.

.. _The Geeky Way: http://TheGeekyWay.com

Footnotes

Refer this blog [#]_ and also this one [#]_.

.. [#] Blog on Markdown
.. [#] Blog on AsciiDoc

Have a look at reST cheatsheet http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt

reStructuredText vs Markdown

I have a prior experience with Markdown. I have always been using Markdown as a format for Readme, changelogs and some time on github issues. But if both Markdown and reST can be used for documentation and creating simple web pages, then who really wins the battle?

This is a hot topic like that of “which text editor is the best?” 🙂

People all over the web discuss, debate and give their opinions about it. Have a look, here is a discussion available on the same. https://news.ycombinator.com/item?id=11922485. And here on Reddit. https://www.reddit.com/r/Python/comments/3zp9g5/markdown_vs_rest/

But I think the gist of this battle lies as follows:

• reST is better for technical documentation such as documenting program libraries, changelogs, API documentation, etc.
• Markdown, on the other hand, is useful for creating simple web-pages, and all non-technical documentation.
• Markdown seems more popular than reST.

But I would like to use both of them as per their use cases.

Conclusion

References:
http://docutils.sourceforge.net/rst.html
https://dgplug.org/irclogs/2012/rst-primer
http://docutils.sourceforge.net/docs/user/rst/quickref.html
https://en.wikipedia.org/wiki/ReStructuredText

I believe reST is a powerful tool that is easy to learn and that you may use for technical documentation purposes. I want to learn and apply more of it. Now let me know what you think about reST in the comments section below 🙂

Thank you!

• All
• Uncategorized