@@ -12,7 +12,7 @@ Setting up the documentation sources
The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation.
Sphinx comes with a script called sphinx-quickstart 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. To use this, enter the below command in windows prompt:
Sphinx comes with a script called sphinx-quickstart 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. To use this, enter the below command in windows prompt to initialise Sphinx project:
.. code:: cpp
...
...
@@ -53,10 +53,127 @@ You add documents listing them in the content of the directive:
For Populating our documentation, refer https://sphinx-rtd-tutorial.readthedocs.io/en/latest/build-the-docs.html
Adding or creating content
Building our Documentation
==========================
In Sphinx source files, you can use most features of standard reStructuredText. Some of the syntax with examples are explained below:
In Sphinx source files, you can use most features of standard reStructuredText. Some of the basic syntax with examples are explained below:
Paragraph
---------
Paragraphs in reStructuredText are blocks of text separated by at least one blank line. All lines in the paragraph must be indented by the same amount:
**Syntax**
.. code-block:: console
* Use one asterisk (*text*) for italic
* Use two asterisks (**text**) for bold
* Use two backticks (``text``) for code sample
**Output**
* Use one asterisk (*text*) for italic
* Use two asterisks (**text**) for bold
* Use two backticks (``text``) for code sample
Headers
-------
Headers are demarcated by non-alphanumeric characters like dashes, equal signs, or tildes. Use the same character for headers at the same level. The following creates a header:
- Document title (h1) use **“#”** for the underline character
- First section heading level (h2) use **“*”**
- Second section heading level (h3) use **“=”**
- Third section heading level (h4) use **“-“**
**Syntax**
.. code-block:: console
Heading one
###########
Heading two
***********
Heading three
=============
Heading four
------------
Bullet Lists
------------
A text block which begins with a **"*"**, **"+"**, **"-"**, **"•"**, **"‣"**, or **"⁃"**, followed by whitespace, is a bullet list item (a.k.a. "unordered" list item). List item bodies must be left-aligned and indented relative to the bullet; the text immediately after the bullet determines the indentation.
**Syntax**
.. code-block:: console
* This is a bulleted list.
* It has two items, the second item uses two lines
**Output**
* This is a bulleted list.
* It has two items, the second item uses two lines.
Numbered Lists
--------------
An numerator consists of a sequence member and formatting, followed by whitespace.
**Syntax**
.. code-block:: console
#. This is a bulleted list.
#. It has two items, the second item uses two lines
**Output**
1. This is a bulleted list.
2. It has two items, the second item uses two lines.
Figure
------
Images are a common use for substitution reference
**Syntax**
.. code-block:: console
.. figure:: <folderpath/filename>
Tables
======
The "list-table" directive is used to create a table from data in a uniform two-level bullet list. "Uniform" means that each sublist (second-level list) must contain the same number of list items:
**Syntax**
.. code-block:: console
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
**Output**
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
Publishing the documentation to ReadTheDocs
...
...
@@ -64,3 +181,12 @@ Publishing the documentation to ReadTheDocs
Once documentation is built, procees to upload it to read the docs. To pubish the document to ReadTheDocs, see https://sphinx-rtd-tutorial.readthedocs.io/en/latest/read-the-docs.html.
