How to Make a Tutorial¶
Tutorials are define using sphinx-gallery.
The sources of tutorials are stored in
docs/gallery with each subfolder corresponding
to a subsection in the tutorial gallery.
Create a new tutorial¶
Add a new python file to the appropriate subfolder of
If you want the output of code cells to be rendered in the docs, then simply
include the prefix
plot_ as part of the name of tutorial file. Tutorials
without the prefix will render just the code cells and text.
Add the names of any files created by running the python file to the
test.py. This function will remove the created output files after the sphinx-gallery tests are completed.
Optional: To specify an explicit position for your tutorial in the subsection of the gallery, update the
GALLERY_ORDERvariable of the
CustomSphinxGallerySectionSortKeyclass defined in
docs/source/conf.py. If you skip this step, the tutorial will be added in alphabetical order.
Check that the docs are building correctly and fix any errors
cd docs make html
View the docs to make sure your gallery renders correctly
Make a PR to request addition of your tutorial
Create a new tutorial collection¶
To add a section to the tutorial gallery
Create a new folder in
docs/gallery/<new-section>/README.txtfile with the anchor name and title of the section, e.g.:
.. _my-new-tutorials: My new tutorial section -----------------------
Add tutorials to the section by adding the tutorial files to the new folder