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