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.

$ 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

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

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 reference and then a Bird

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.

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

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

Example:

  .. code-block:: python

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

Example:

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

Example:

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

Share this Blog post

Facebook X Linkedin