How to add a how-to guide

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 a how-to guide 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 guide

In order to create a how-to guide, go to the docs/how_to folder of your project repository and add a new .rst file there. In this guide we will assume your guide is called your_guide.rst.

Update the page

Once you have created and written your file, you need to update the docs/how_to/index.rst file so your new guide appears in the web page.

In particular, you only need to include your new guide in a toctree like this one:

Section name
============

.. toctree::
   :maxdepth: 1

   existing_guide_1
   Title of second existing guide <existing_guide_2>
   Title of your guide <your_guide>

In this example, the title from the first existing guide (existing_guide_1.rst) is taken directly from it while for existing_guide_2.rst and your new guide 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.