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
docs/gallery
.
Hint
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
files_to_remove
variable inclean_up_tests()
intest.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_ORDER
variable of theCustomSphinxGallerySectionSortKey
class defined indocs/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
open docs/_build/html/index.html
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>
Create a
docs/gallery/<new-section>/README.txt
file 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