Writing reST

Ever wondered how documentation, blogs, online books (not the PDFs) are written? Well, if it’s a really big one, RST (or reST) is the best shot.

 

The name reStructuredText was chosen to indicate that it is a “revised, reworked, and interpreted StructuredText”. reStructuredText is also abbreviated as RST, ReST and reST. (Wikipedia)

The official Python documentation uses RST. You can see the primer of the RST they use here

I followed the reStructuredText Primer by kushal and created a test.rst for me.

To convert RST to an HTML page, you’d need to install two packages namely: python3-docutils and python3-sphinx

and then you can use the command:

rst2html test.rst test.html

This will generate HTML page based on the RST you wrote in test.rst. Without test.html the output is just sent to the stdout.

If you don’t have rst2html command after installing the said two packages, you can try pressing the tab key to see if it is installed by some other name.

Let’s follow along with some snippets:

Headings

First the title of the doc.

======
Title
======

Here remember to keep the upper and lower lines equal, and you can skip the upper one.

Then you can write the texts and para like normal text for example:

This will come as a simple sentence.

And this as another para, due to space between them.

If you don’t leave any line between two sentences, then they are joined into one.

Commenting

To comment, we use .. like:

.. This is a comment

Space between .. and the comment is required. Most of the issues that I ran into were resolved by trying to put a space or a new line while trying out RST.

A comment can be multiline in which case it’s length is determined from the indentation.

..
  This is a multiline
  comment.

Section title can be given in a similar manner to the doc title.

Section Title
==============

According to sphinx documentation, the following convention is preferred as it is used in the python style guide.

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

I didn’t know this so in my test.rst I tried playing to get it all correct 😛

Lists

Lists are the simplest part. Unordered list has a syntax:

* First Item
* Second
* And this is Third

“This text is not in the list due to the absence of ‘*’”

Ordered List can be generated manually or automatically like:

1. Some text
2. Other text
   more text with "other text"


1. This 
#. Is
#. An
#. Autonumbered list

a. This
#. Is 
#. Also
#. Autoindexed

Definition list

This is a set of text indented relative to each other. Point to note here is that, there should be a blank line just before and after the definition list.

Some term
    It's definition

Some other term:
    It's definition

Option list

The options list is used to write command line tools’ option and description. This is one of my favorites too!

-a      Option a
-b      This is b option
        with longer description
--some  This is another option

Remember to leave lines before and after starting a new body element. This was the thing I messed up most.

Literal blocks

If you are writing about RST in RST, then what? You need literal blocks for such cases. They are not interpreted and are printed as it is.

::

    This is a literal block
    for a in ['a', 'b', 'c', 'd']:
        print(a)
    print("some content")
    # A python comment

Doctest Block

These are interactive python sessions pasted in the text. When I first tried RST, I thought these were supposed to be evaluated in Python :P. But these are for explanation purposes, to show examples, and to provide a method to test the documentation’s content using doctest modules

>>> print("This is a python command")
This is a python command

The command and the output are both written by the writer.

Creating Tables

Creating a table is another easy task though it requires some typing effort.

===   ===   ===
 a     b     c
===   ===   ===
1     2     3
3     2     1
===   ===   ===

Another form of a table is:

+--------+--------+
|Another | form   |
+--------+--------+
|of      |creating|
+--------+--------+
|a       |table   |
+--------+--------+

Though this is more readable, it is slightly strenuous on your fingers. But I still like this one :P.

Note: This table might appear malformed on wordpress. You can try copying it to an editor locally.

Creating links

This is a normal hyperlink

`link text <https://www.duckduckgo.com>`_

This is an example of a targeted hyperlink:

`text which isn't linked currently`_ This is text apart from it

.. _text which isn't linked currently: https://www.duckduckgo.com

Notes

You can also give notes in the text.

.. note:: This is a note

But this isn't

Emphasis

You can put * around your text to put the emphasis. Generally, it italicises the content it surrounds.

To make the content bold you can use **

This text is *italicised* and this **bold**

Footnotes

To give more links for further reading and clarifications, you can give footnotes. They can also be autonumbered.

This is footnote one [#]_ and this two [#]_.

Some text between the footnote text and links.

.. [#] Hey I'm footnote one
.. [#] You can refer to the official docs for more!

Some text after footnote

Note that the text before and after footnote links isn’t compulsory. I just added it so that I know that it’s possible too.

This must be it.

Till the next time, don’t rest but go reST!

 

storymode7

Advertisements

One Comment Add yours

  1. comprehensive, structured, succinct.
    write more so that the language improves too. (it is, slowly)

    well done! 🙂

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s