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!
You’ve really upped your game!
well thought. well structured. well executed.
This was a joy to read
LikeLiked by 1 person
Thank you 🙂
LikeLiked by 1 person