Adding Examples to the Gallery#
This guide explains how to add new examples to the IMPROVER examples gallery.
Adding a New Example#
To add a new example to this gallery:
Create a Python file in the
doc/source/examples/directory with a descriptive name.Follow the format of existing examples like
thresholding_simple_example.py:Start with a docstring (triple quotes) containing a title with equals signs above and below
Add a description of what the example demonstrates
Include author and license information
Use
# %%to separate code cellsAdd comments or section headers (using
# %%followed by description lines) to explain each step
Alternatively, you can create a Jupyter notebook and convert it to a Sphinx-Gallery compatible Python file using
jupytext:jupytext --to py:percent --opt notebook_metadata_filter='-all' your_notebook.ipynb
Sphinx-Gallery will automatically:
Generate a thumbnail from the first figure
Convert the script to a reStructuredText page
Add it to this gallery
Create a downloadable Jupyter notebook version
Build the documentation to see your example in the gallery.
Using Real Data in Examples#
If you want to create examples that use real data files:
Add the data files to the improver_example_data repository.
Create a branch in the
improver_example_datarepository with your data files.When creating a pull request in this repository (
improver), note the PR number (e.g.,123). Create a branch inimprover_example_datawith the same number as the PR number (e.g., branch named123). This ensures that the documentation build for the pull request preview can access the correct version of the example data.Alternatively, for local development, you can create matching branch names in both repositories instead of using PR numbers.
In your example script, use the
example_data_path()function to reference the data files:from improver import example_data_path data_file = example_data_path("subdirectory", "filename.nc")
When both pull requests are merged, the documentation will automatically use the example data from the
masterbranch ofimprover_example_data.