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.
reST files have the extension
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
The first step is to install these tools
Now create any file (say
doc.rst) and let’s try out the following examples.
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.
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.
This is a section title =======================
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.
- object 1 - object 2
1. object 1 2. object 2
Term 1: optional_classifier This is definition 1.
-a purpose of attribute 'a' -out purpose of attrubute 'out'
:Student: Name of student :Enroll: Student's enrollment number
:: 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.
| this is a | line block | useful for | writing addresses
These are simply: indented paragraphs
Doctest blocks are interactive Python sessions. They begin with:
>>>like >>> print "This is a doctest block." This is a doctest block.
.. 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
This is `title <link>`_
`The Geeky Way`_ is a technical blog. .. _The Geeky Way: http://TheGeekyWay.com
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.
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 🙂