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
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 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 
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.
Django-CRM :Customer relationship management based on Django
Django-blog-it : django blog with complete customization and ready to use with one click installer Edit
Django-webpacker : A django compressor tool
Django-MFA : Multi Factor Authentication
Docker-box : Web Interface to manage full blown docker containers and images
More...