Introduce cset_gallery functionality - #2242
Conversation
Total coverage: 92% (HTML report)Name Stmts Miss Branch BrPart Cover --------------------------------------------------------------------------------------------------- src/CSET/__init__.py 104 0 14 0 100% src/CSET/_common.py 149 0 52 0 100% src/CSET/cset_workflow/app/fetch_fcst/bin/fetch_data.py 116 28 26 0 77% src/CSET/cset_workflow/app/fetch_nimrod/bin/fetch_nimrod.py 80 8 28 11 82% src/CSET/cset_workflow/app/finish_website/bin/finish_website.py 79 2 8 2 95% src/CSET/cset_workflow/app/parbake_recipes/bin/parbake.py 29 0 8 0 100% src/CSET/cset_workflow/app/send_email/bin/send_email.py 25 0 4 0 100% src/CSET/cset_workflow/lib/python/jinja_utils.py 17 0 6 0 100% src/CSET/extract_workflow.py 103 3 26 3 95% src/CSET/graph.py 43 0 14 0 100% src/CSET/operators/__init__.py 89 0 26 0 100% src/CSET/operators/_atmospheric_constants.py 9 0 0 0 100% src/CSET/operators/_colormaps.py 243 1 64 2 99% src/CSET/operators/_stash_to_lfric.py 3 0 0 0 100% src/CSET/operators/_utils.py 193 8 76 6 95% src/CSET/operators/ageofair.py 141 7 64 5 94% src/CSET/operators/aggregate.py 76 1 22 1 98% src/CSET/operators/aviation.py 60 0 18 0 100% src/CSET/operators/collapse.py 154 8 72 3 93% src/CSET/operators/constraints.py 113 7 50 3 93% src/CSET/operators/convection.py 37 4 10 2 87% src/CSET/operators/ensembles.py 27 0 14 0 100% src/CSET/operators/feature.py 41 0 10 0 100% src/CSET/operators/filters.py 66 2 30 0 98% src/CSET/operators/fluxes.py 41 0 10 0 100% src/CSET/operators/humidity.py 139 0 56 0 100% src/CSET/operators/imageprocessing.py 56 0 16 0 100% src/CSET/operators/mesoscale.py 17 0 2 0 100% src/CSET/operators/misc.py 172 1 74 4 98% src/CSET/operators/plot.py 1026 164 370 76 80% src/CSET/operators/power_spectrum.py 97 3 30 3 95% src/CSET/operators/precipitation.py 204 2 92 2 99% src/CSET/operators/pressure.py 41 0 12 0 100% src/CSET/operators/read.py 433 22 190 18 93% src/CSET/operators/regrid.py 146 1 70 3 98% src/CSET/operators/scoreswrappers.py 160 22 42 8 82% src/CSET/operators/temperature.py 121 0 32 0 100% src/CSET/operators/transect.py 62 0 24 0 100% src/CSET/operators/wind.py 45 3 10 2 91% src/CSET/operators/write.py 15 0 6 0 100% src/CSET/recipes/__init__.py 104 0 28 0 100% --------------------------------------------------------------------------------------------------- TOTAL 4876 297 1706 154 92% |
059c4fa to
9f0ddea
Compare
James Frost (jfrost-mo)
left a comment
James Frost (jfrost-mo)
left a comment
There was a problem hiding this comment.
Overall this gallery would be an excellent addition to the CSET documentation. The approach is sensible, and produces good looking output. I've suggested a few changes throughout, but nothing that majorly changes the approach.
|
|
||
| [tool.ruff.lint] | ||
| extend-select = ["B", "D", "I"] | ||
| per-file-ignores = {"docs/source/reference/cset_gallery/examples/**/*.py" = ["D"]} |
There was a problem hiding this comment.
Were any specific lints causing trouble here? I'd be inclined to keep them checked if we can.
There was a problem hiding this comment.
Sensible change, but should be extracted into a separate (tiny) PR to it doesn't distract from this one.
| :maxdepth: 1 | ||
|
|
||
| glossary | ||
| cset_gallery/index |
There was a problem hiding this comment.
Given we are in the CSET documentation already the additional cset_ is redundant. We can just have the folder be gallery.
| :orphan: | ||
|
|
||
|
|
There was a problem hiding this comment.
This page has been added to the reference doctree, so it isn't an orphan.
| @@ -0,0 +1 @@ | |||
| .. orphan | |||
There was a problem hiding this comment.
I could be wrong on this, but I don't think this .. orphan is doing anything, given this is the comment syntax. If so it can be removed from all the files with it.
|
|
||
| .. code-block:: | ||
|
|
||
| cset cookbook generic_surface_spatial_plot_sequence |
There was a problem hiding this comment.
| cset cookbook generic_surface_spatial_plot_sequence | |
| cset cookbook generic_surface_spatial_plot_sequence.yml |
I can't remember if the change has landed yet or not, but it is better to use the full filename (including the .yml suffix) if you can.
I might even remove the partial matching, as it causes issues when you have two recipes that share a prefix. For example spatial_plot.yml and spatial_plot_mean.yml both get selected if you query with just "spatial_plot".
|
|
||
|
|
||
| A) Using *cset bake* on the command line | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
There was a problem hiding this comment.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| ---------------------------------------- |
While it functions fine ideally we match the heading order that other pages use. So === underlines for first level headings, --- underlines for second, and ~~~ for third level headings. (I should probably document this in some kind of style guide...)
|
|
||
| Spatial maps are generated using either CSET operators :py:mod:`CSET.operators.plot.spatial_pcolormesh_plot` or :py:mod:`CSET.operators.plot.spatial_contour_plot`. | ||
|
|
||
| General functionality is provided using :doc:`CSET recipe </usage/operator-recipes>` ``generic_surface_spatial_plot_sequence.yaml`` |
There was a problem hiding this comment.
I'm undecided on whether we want to list the operators used. On the one hand they can be looked up, on the other it is useful to explicitly say why they are being used in this example to facilitate learning.
If we do keep them I think we should formalise it a bit more. Maybe have a section for used operators with a definition list of operators used and what they do in this case? Something like:
Operators
---------
:py:mod:`CSET.operators.read.read_cubes`
Loads the a cube of data from a file.
:py:mod:`CSET.operators.plot.spatial_contour_plot`
Plots a spatial contour plot of the domain.It might get a bit verbose however. Would we be better off trying to link them in the code, like matplotlib's examples do?
There was a problem hiding this comment.
Apparently these section header files should now be called GALLERY_HEADER.rst instead of README.rst. https://sphinx-gallery.github.io/stable/configuration.html#nesting-gallery-sections
There was a problem hiding this comment.
We will need to add the sphinx-gallery package to requirements/environment.yml, under the Documentation dependencies. This will them allow the gallery to build via GitHub Actions, and will allow developers checking out this branch (and running make setup) to build the documentation.
|
Note that during review I rebased the pull request to get it building against the lastest version of main. This requires you to update your local development copy as follows: # Fetch the latest changes from GitHub
git fetch
# Ensure you are on the right branch.
git switch 2231-generate-docs-gallery
# Reset your local branch to match the copy on GitHub.
git reset --hard origin/2231-generate-docs-gallery |
|
An additional thing is to add to the .gitignore so the generated files don't get shown by git. (This might also be another reason to better control when the meta.json/index.html files are generated.) |
7 participants
Contribution checklist
Aim to have all relevant checks ticked off before merging. See the developer's guide for more detail.
rose-suite.conf.examplehas been updated if new diagnostic added.