reStructuredText-Basics.rst

Documentation using Sphinx

This topic aims to describe a standard way of documenting using reStructuredText with Sphinx and publising to ReadTheDocs. reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document.

Sphinx installation

Sphinx is written in Python and supports Python 3.6+. It builds upon the shoulders of many third-party libraries such as Docutils and Jinja, which are installed when Sphinx is installed. For more details on Sphinx Installation, see https://www.sphinx-doc.org/en/master/usage/installation.html.

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 to initialise Sphinx project:

sphinx-quickstart

The below quickstart screen appears as shown below:

Figure 1 quickstart utility

For more information on Sphinx Quickstart, refer https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-quickstart.html.

Defining Document Structure

sphinx-quickstart creates a source directory with conf.py and a master document, and index.rst. The main function of the master document is to serve as a welcome page, and to contain the root of the “table of contents tree” (or toctree). index.rst is the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.

The toctree directive initially is empty as below:

.. toctree::
:maxdepth: 2

You add documents listing them in the content of the directive:

.. toctree::
:maxdepth: 2

usage/installation
usage/quickstart

For Populating our documentation, refer https://sphinx-rtd-tutorial.readthedocs.io/en/latest/build-the-docs.html

Building our Documentation

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

* 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

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

* 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

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

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

=====  =====  =======
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

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.

Reference

https://www.sphinx-doc.org/en/master/contents.html

https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

https://docs.zephyrproject.org/latest/guides/documentation/index.html