Building Documentation with readthedocs

Reading Time : ~ .

In this blog, I'm going to explain you how to write the Sphinx docs using reStructuredText to host in the Read the Docs.

Installing Sphinx

  $ pip install Sphinx

And we have script called sphinx-quickstart in Sphinx that sets up a source directory and creates a default with the most useful configuration values from a few questions it asks you. Just run the following command-

  $ sphinx-quickstart

For more details on installation process, please go through here.

Getting Started

After installing Sphinx, you will be having a master document(index.rst) created. It contains the table of contents(toctree).

You can add the documents to it like

  .. toctree::
   :maxdepth: 2


Now you can add the content in those newely created documents in standard reStructuredText. There are also several features added by Sphinx.

reStructuredText (reST)

reStructuredText is an easy-to-read markup language. reStructuredText is just a plaintext that uses simple syntaxes to indicate the structure of a document.


Section headers are created by underlining the section title

  Section Title        (OR)    Section Title
  ===============              ==============

  SubSection Title     (OR)    SubSection Title
  ------------------           -----------------

Heading levels are determined from the succession of headings

  =, for sections
  -, for subsections
  ^, for subsubsections


Paragraphs consist of blocks of left-aligned text. Blank lines separate paragraphs from each other.

  This is the first sentence in a new paragraph. This is the second sentence in a new paragraph. This is the third sentence in a new paragraph. And so on

  Second paragraph

Inline Markup

The reST inline markup is quite simple:

  *text*                      -   Renders as italics.
  **text**                    -   Renders as bold.
  reference_                  -   A single word hyperlink reference.
  `phrase reference`_         -   A hyperlink reference with spaces or punctuation.
  |substitution reference|    -   The result is substituted in from the substitution 
                                  definition. It could be text, an image, a hyperlink.

  `word_reference`_ and `some phrase reference`_ and then a |substitution|

  .. _word_reference:

  .. _some phrase reference:

  .. |build-status| image::
    :alt: Bird

  Results -

word_reference and some phrase referenceand then a Bird

Escaping with Backslashes

reStructuredText uses backslashes ("\") to override the special meaning given to markup characters.

  *escape* ``with`` "\"

  Results - 

  escape with ""


List Markup syntax is simple. Just place an asterisk at the start for bulleted list, place a respective number for numbered lists.

  * This is a bulleted list.
  * Bullets are "-", "*" or "+".
  * It has many items, the third item uses two or more
    lines. Continuing text must be aligned after the 
    bullet and whitespace.

      * with a nested list subitems
      * and some more subitems

  * and here the parent list continues
  * and some more parent list items

  1. This is a numbered list.
  2. It has two items too.

  #. This is also a numbered list.
  #. It has two items too.

  Note: A blank line is required before the first item and after the last item.

Source Code

Code blocks can be written by ending a paragraph with the special marker ::.

  This is a first paragraph::

    And this the code block.
    It can multiple lines.

    You can write write your code here.

  Note: A blank line is required to separate two paragraphs from each other.

  Please see the below code::


Example Template

                   And now we are out of the code block which will normally be rendered as a paragraph.

The other way of writing code-blocks is

  .. code-block:: python or javascript or html

    $ your normal code
    $ Import, logic, html codes etc


  .. code-block:: python

    $ git init
    $ git config "Your name"



  .. note:: You can write your 'note' here. This is the note.
            It can multiple lines. 



  .. warning:: You can write your 'warning' here.
               This is the warning message.
    By Posted On

Need any Help in your Project?Let's Talk

Latest Comments
Related Articles
How to get self motivated to achieve goals Anusha Damacharla

Self Motivation is important to achieve success in life. Motivation is what Pushes us to achieve our goals, One of the biggest challenge is meeting ...

Continue Reading...
Streaming Protocols continued... RTMP, MMS Ashwin Kumar

Streaming is the technique for transferring data at fixed rate in real time between the client and the server. There are many streaming protocols available ...

Continue Reading...
Tracking your Product Sales, Views and Searches with Google Enhanced E-commerce Analytics Jagadeesh V

Enhanced E-commerce helps improving tracking of an ecommerce website. It gives Statistics in variable measurements. It is not be used alongside analytics plugin, as this ...

Continue Reading...

Subscribe To our news letter

Subscribe to our news letter to receive latest blog posts into your inbox. Please fill your email address in the below form.
*We don't provide your email contact details to any third parties