Building Documentation with readthedocs

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 conf.py 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

   document-name-here
   document1
   document1
   ...

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.

Sections:

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:

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.

  Example:

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

  .. _word_reference: http://example.org/

  .. _some phrase reference: http://somedomain.org/

  .. |build-status| image:: https://www.example.com/bird.png
    :alt: Bird

  Results -
      

word_reference and some phrase referenceand then a

Escaping with Backslashes

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

  *escape* ``with`` "\"

  Results - 

  escape with ""

Lists

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.

  Example:

  Please see the below code::

    

Example Template

The other way of writing code-blocks is

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

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

  Example:

  .. code-block:: python

    $ git init
    $ git config user.name "Your name"

Note

  Example:

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

Warning

  Example:

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