3. Configure your Sphinx documentation¶

Ok, now we want to customize/configure our Sphinx documentation. The docs/conf.py file play a crucial role. Have a look at it!

It is a Python file, so it can definitely contain Python logic. However it is mostly use to define some variables. For example, the theme is associated with the variable html_theme. Let’s change its value to see what happens.

3.1. Change the theme¶

We will try to substitute the basic theme with a prettier one. We choose the furo theme.

First, we need to install it:

poetry add furo --group docs

Then, in docs/conf.py, change html_theme to html_theme = "furo".

Finally, build the documentation! (make html).

It looks better, doesn’t it?

3.2. Change the title¶

The current title is a bit long. Let’s put only NeuroPlot as title.

In docs/conf.py, add html_title = "NeuroPlot".

3.3. Add a logo¶

We still miss a logo! There’s no official NeuroPlot logo yet, so let’s use ARAMIS logo.

We can download it here.

And then put it in docs/_static/logos. As you have guess, the _static folder is where you will put all the images or other resources that you want your website to use.

Finally, in docs/conf.py, add the variable html_logo = "_static/logos/logo_ARAMISLAB_rvb.png".

As usual, build your documentation to see the result!

3.4. Improve design¶

I don’t know about you, but I’m not totally satisfied with the home page. I would like to improve its design. To do that, we will use the sphinx-design extension.

First, we need to install it:

poetry add sphinx-design --group docs

Then, we will tell Sphinx to use it. In docs/conf.py, change extensions to extensions = ["sphinx_design"].

Now, we can use its features. For example, change your docs/index.rst to:

3.5. Other improvements¶

I think you’re beginning to understand how it works: to change settings in our documentation, we change/add variable in docs/conf.py. Sometimes, we also need to install extensions.

To make sure you’re completely comfortable with Sphinx settings, let’s take as examples two other features that we would like to implement:

in our Installation page, we will probably have commands that the user would like to copy easily, so we would like a copy button;
as mentioned earlier, we would like Sphinx to be able to read markdown files.

To implement these features, we will use respectively sphinx-copybutton and myst-parser:

Install the extensions:

poetry add sphinx-copybutton --group docs
poetry add myst-parser --group docs

Add the extensions in docs/conf.py:

extensions = [
    "sphinx_design",
    "sphinx_copybutton",
    "myst_parser",
]

Test the functionalities:

Change docs/installation.rst to:

Installation
============

.. code-block:: bash

    pip install neuroplot

Replace docs/contributing.rst with a docs/contributing.md:

rm contributing.rst
echo "# Contributing" > contributing.md

Rebuild and have a look at the result in your website!

I hope Sphinx configuration is clear now. Please understand that we have only mentioned a few examples of the many features offered by Sphinx.

Our documentation looks great, but a central element is still missing the API Reference.

If you don’t manage to run the tutorial

git reset --hard 85031f317632af1eea7381c1f2dfdd461fd7c53c