$ 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-
For more details on installation process, please go through here.
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 -
Escaping with Backslashes
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 TemplateAnd now we are out of the code block which will normally be rendered as a paragraph.
The other way of writing code-blocks is
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.