Adding pages#

Let’s add a new section to our documentation to contain the user guide.

cd docs
echo "User guide\n==========" > user-guide.rst

Now, add the new page to the table of contents at the top of index.rst.

index.rst#
.. toctree::
   :maxdepth: 2

   user-guide

In user-guide.rst we can add a TOC tree to other pages in the documentation relating to the user guide. For example, let’s create a page for installation instructions and a page for release notes contained in a new directory.

mkdir user-guide; cd user-guide
echo "Installation\n============" > installation.rst
echo "Release notes\n=============" > release-notes.rst

We then add the new pages to the table of contents at the top of user-guide.rst.

user-guide.rst#
.. toctree::
   :maxdepth: 2

   user-guide/installation.rst
   user-guide/release-notes.rst

You may then go into installation.rst and release-notes.rst and write the documentation.

Documentation is generated from reStructuredText files (.rst or .rest). For a primer on reStructuredText, see here. Below, we will cover a few basics.

Note

If you prefer to use markdown over reStructuredText, you can use the MyST extension. If so, you may skip the rest of this chapter.

Headings#

There are several ways to create headings in reStructuredText, but simply you may underline the headings like so,

  • = for sections

  • - for subsections

  • ^ for subsubsections

  • " for paragraphs

Lists#

Lists can be, e.g. numbered,:

1. First item
2. Second item
3. Third item

autonumbered,:

#. First item
#. Second item
#. Third item

or bullets,:

* First item
* Second item
* Third item

Code blocks#

Code blocks may be written with syntax highlighting like so,

.. code-block:: python
   :caption: hello-world.py
   :linenos:

   # print "Hello world!"
   print("Hello world!")

which renders as,

hello-world.py#
1# print "Hello world!"
2print("Hello world")

Example#

For this documentation, user-guide.rst looks like this:

user-guide.rst#
User guide
==========

This is an example user guide to the ASR Code Review documentation tutorial.
You can emphasises text like *this* and embolden text like **this**. Inline
code can be written like ``this`` and hyperlinks can be written like
`this <https://www.youtube.com/watch?v=dQw4w9WgXcQ>`_.

.. toctree::
   :maxdepth: 2

   user-guide/installation.rst
   user-guide/release-notes.rst