How to add an explanation¶
Note
This page was written in the style of a How-to Guide according to The Diátaxis Framework.
This guide shows how to add an explanation to a project repository.
Pre-requisites¶
This guide assumes your project already has a working Sphinx documentation project in a
folder called docs
and the recommended folder structure. If you don’t
have it, you can set it up with sphinx-quickstart following the tutorial Create a New Documentation Project.
Create a new explanation¶
In order to create an explanation, go to the docs/explanations
folder of your project repository and add a new .rst
file there. In this guide we will assume your explanation is called your_explanation.rst
.
Update the page¶
Once you have created and written your file, you need to update the docs/explanations/index.rst
file so your new explanation appears in the web page.
In particular, you only need to include your new explanation in a toctree
like this one:
Section name
============
.. toctree::
:maxdepth: 1
existing_explanation_1
Title of second existing explanation <existing_explanation_2>
Title of your explanation <your_explanation>
In this example, the title from the first existing explanation (existing_explanation_1.rst
) is taken directly from it while for existing_explanation_2.rst
and your new explanation
the title is set manually.
It’s important to make sure that the indentation of the items inside the toctree
is of at least three whitespaces.