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.
Micropyramid is a software development and cloud consulting partner for enterprise businesses across the world. We work on python, Django, Salesforce, Angular, Reactjs, React Native, MySQL, PostgreSQL, Docker, Linux, Ansible, git, amazon web services. We are Amazon and salesforce consulting partner with 5 years of cloud architect experience. We develop e-commerce, retail, banking, machine learning, CMS, CRM web and mobile applications.
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...