How to add a tutorial¶
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 tutorial to your 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 tutorial¶
In order to create a tutorial, go to the docs/tutorials
folder of your Qiskit project repository and add a new .ipynb
or (prefereably) .rst
file there. In this guide we will assume your tutorial is called your_tutorial.ipynb
or your_tutorial.rst
.
Note
If the tutorial is an ipynb
file, nbsphinx
needs to be included in the extensions
variable of docs/conf.py
to convert the ipynb
file into an rst
file during the documentation building process.
Update the page¶
Once you have created and written your file, you need to update the docs/tutorials/index.rst
file so your new tutorial appears in the web page.
.rst
¶
If your tutorial is an .rst
file, add it to a toctree
like this one:
Section name
============
.. toctree::
:maxdepth: 1
existing_tutorial_1
Title of second existing tutorial <existing_tutorial_2>
Title of your tutorial <your_tutorial>
In this example, the title from the first existing tutorial (existing_tutorial_1.rst
) is taken directly from it while for existing_tutorial_2.rst
and your new tutorial
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.
The section name header needs to be covered by equal signs =
below.
.ipynb
¶
If your tutorial is an .ipynb
file, add it to a nbgallery
like this one:
Section name
============
.. nbgallery::
:maxdepth: 1
existing_tutorial_1
Title of second existing tutorial <existing_tutorial_2>
Title of your tutorial <your_tutorial>
The nbgallery
directive has the same arguments as toctree
, so the only
difference between this case and the .rst
one is writing the name of the directive.