Generating a gallery with sphinx-gallery¶
sphinx-gallery lets us generate scripts using reStructuredText alongside python.
This means that we can include formatting to make it easier to follow our work.
Let’s add the next few blocks of code to our trapezoid plot and see how it looks.
Add the following sections of text to the plot_trapezoid.py file in the examples
folder.:
###############################################################################
# Define our function
# -------------------
#
# Below we'll define a function that we'll integrate
# $$ 2.2a^3 + .3a^2 + 2a + .1 $$
###############################################################################
# Now plot the function
# ---------------------
#
# Using this function, we'll plot the function itself for a range of
# points.
###############################################################################
# Finally, plot the area
# ----------------------
#
# Finally we'll show how the area under the curve changes as a
# function of how many points we use to create the trapezoids.
Changing the chosen gallery image¶
We can also manually choose the image we want for the gallery. Add this comment to the beginning of the script to do so:
# sphinx_gallery_thumbnail_number = 2
Now build the documentation:
make html
and open the built page for the trapezoid example:
../sphinx_template/docs/build/html/auto_examples/plot_trapezoid.html
Note
We should also update our index.rst file so that the built gallery shows
up in our table of contents.:
auto_examples/index
Adding a subfolder of gallery images¶
If we have multiple galleries, we can easily pass them to sphinx-gallery by using sub-folders in our examples folder. Let’s split our two examples into their own folders.
Note that we need to have a README.txt file for each folder.
Wrapping up¶
sphinx-gallery has many more things you can do with it, and we encourage you to check
out their documentation to learn more about this toolbox.
If you want some inspiration, you can find a list of projects
using sphinx-gallery on their github readme.
