2. Write documentation pages

Now that we have a functional documentation, we will fill it. As suggested in the introduction, we will add Installation, Getting Started, User Guide, API Reference, and Contribution Guide sections:

echo "Installation\n============" > installation.rst
echo "Getting Started\n===============" > getting_started.rst
mkdir -p user_guide && echo "User Guide\n==========" > user_guide/index.rst
echo "10 minutes to NeuroPlot\n=======================" > user_guide/intro.rst
echo "Plotting a 3D image\n===================" > user_guide/plot.rst
echo "Making a GIF\n============" > user_guide/gif.rst
echo "Multiple plots\n==============" > user_guide/multiple_plots.rst
mkdir -p api && echo "API Reference\n=============" > api/index.rst
echo "Contributing\n============" > contributing.rst

Note

These commands are just here to make your life easier. Of course, you could have created the .rst files manually.

Have a look at your docs folder: .rst files are placed at the same level as your index.rst. Besides, if you want a page with subpages (e.g. the User Guide here), you will create a folder, with an index.rst inside.

However, if you build the documentation (make html), you will not see any modification. The new pages are not visible in our documentation… But they have been built: for example, the Installation page is accessible at http://localhost:8888/installation.html. This simply because we have to feed the table of contents in our docs/index.rst pages:

  1. Change the content of docs/index.rst with:

NeuroPlot
=========

NeuroPlot is a Python library for plotting neuroimaging data.

.. toctree::
    :maxdepth: 1

    installation
    getting_started
    user_guide/index
    api/index

.. toctree::
    :caption: development
    :maxdepth: 1

    contributing
    GitHub <https://github.com/aramis-lab/tuto-doc>

  1. Change the content of user_guide/index.rst with:

User Guide
==========

.. toctree::
    :numbered:

    intro
    plot
    multiple_plots
    gif

  1. Build the documentation.

Can you see the new pages in the navigation bar?

Great, now let’s talk about that weird .rst extension…

2.1. reStructuredText format

rst stands for “reStructuredText”. It is a convenient format to write documentation. It is very similar to the simpler and well-know markdown, although it is a bit more powerful.

We won’t dive into an extended presentation of rst syntax because we have a lot of things to do today, and there are already many resources to get started with it (e.g. have a look a this quickstart, or this one; and here is a cheatsheet).

Besides, this tutorial is entirely written in rst, so it will give you an overview of what you can do with this syntax.

2.2. markdown

If you are reluctant to learn a new syntax or if you think that markdown is enough for what you want to do, you can still configure Sphinx so that it reads .md files. To do this, let’s take a look at how to configure our documentation.

If you don’t manage to run the tutorial

git reset --hard 450ad27d9616201396af4c761c10cbf149f4b769