iris

iris copied to clipboard

📚 Documentation

Below is a list of all the python files in iris/lib. In order to make ground ensuring our code based support numpdoc fully the below checklist can be used to track our progress.

Recommend we slowly work thru this list using multiple pull requests, all may contribute!

For each file we should:

• Apply numpdoc string formatting. See guidance in our documentation: https://scitools-iris.readthedocs.io/en/latest/developers_guide/documenting/docstrings.html#docstrings
• Ensure it renders ok using the numpdoc formatting when Building the Documentation
• Consider improving the docstring content, not just the formatting.
• Clarify laziness status (if appropriate). See https://github.com/SciTools/iris/issues/3292

Commands used to create the list: cd lib/iris; find . -name "*.py" -print | grep -v "^./tests". Feel free to remove entries is they are not relevant.

• [ ] ./init.py
• [ ] ./_concatenate.py
• [ ] ./_constraints.py
• [ ] ./_merge.py
• [ ] ./_data_manager.py
• [ ] ./_deprecation.py
• [ ] ./_lazy_data.py
• [ ] ./aux_factory.py
• [ ] ./analysis/init.py @rcomer
• [ ] ./analysis/_area_weighted.py
• [ ] ./analysis/_grid_angles.py
• [ ] ./analysis/_interpolation.py
• [ ] ./analysis/_regrid.py
• [ ] ./analysis/_scipy_interpolate.py
• [ ] ./analysis/calculus.py
• [ ] ./analysis/cartography.py
• [ ] ./analysis/geometry.py
• [ ] ./analysis/maths.py
• [ ] ./analysis/stats.py
• [ ] ./analysis/trajectory.py
• [ ] ./util.py
• [ ] ./config.py
• [ ] ./coord_categorisation.py
• [ ] ./coord_systems.py
• [ ] ./coords.py
• [ ] ./cube.py
• [ ] ./exceptions.py
• [ ] ./experimental/init.py
• [ ] ./experimental/animate.py
• [ ] ./experimental/raster.py
• [ ] ./experimental/regrid.py
• [ ] ./experimental/regrid_conservative.py
• [ ] ./experimental/representation.py
• [ ] ./experimental/stratify.py
• [ ] ./experimental/ugrid/init.py
• [ ] ./experimental/ugrid/cf.py
• [ ] ./experimental/ugrid/load.py
• [ ] ./experimental/ugrid/mesh.py
• [ ] ./experimental/ugrid/metadata.py
• [ ] ./experimental/ugrid/save.py
• [ ] ./experimental/ugrid/utils.py
• [ ] ./fileformats/init.py
• [ ] ./fileformats/_ff.py
• [ ] ./fileformats/_ff_cross_references.py
• [ ] ./fileformats/_pp_lbproc_pairs.py
• [ ] ./fileformats/_structured_array_identification.py
• [ ] ./fileformats/abf.py
• [ ] ./fileformats/cf.py
• [ ] ./fileformats/dot.py
• [ ] ./fileformats/name.py
• [ ] ./fileformats/name_loaders.py
• [ ] ./fileformats/netcdf.py
• [ ] ./fileformats/nimrod.py
• [ ] ./fileformats/nimrod_load_rules.py
• [ ] ./fileformats/pp.py
• [ ] ./fileformats/pp_load_rules.py
• [ ] ./fileformats/pp_save_rules.py
• [ ] ./fileformats/rules.py
• [ ] ./fileformats/um/init.py
• [ ] ./fileformats/um/_fast_load.py
• [ ] ./fileformats/um/_fast_load_structured_fields.py
• [ ] ./fileformats/um/_ff_replacement.py
• [ ] ./fileformats/um/_optimal_array_structuring.py
• [ ] ./fileformats/um_cf_map.py
• [ ] ./fileformats/_nc_load_rules/init.py
• [ ] ./fileformats/_nc_load_rules/actions.py
• [ ] ./fileformats/_nc_load_rules/engine.py
• [ ] ./fileformats/_nc_load_rules/helpers.py
• [ ] ./io/init.py
• [ ] ./io/format_picker.py
• [ ] ./iterate.py
• [ ] ./palette.py
• [ ] ./pandas.py
• [ ] ./plot.py
• [ ] ./quickplot.py
• [ ] ./symbols.py
• [ ] ./time.py
• [ ] ./_representation/init.py
• [ ] ./_representation/cube_printout.py
• [ ] ./_representation/cube_summary.py
• [ ] ./std_names.py
• [ ] ./common/init.py
• [ ] ./common/lenient.py
• [ ] ./common/metadata.py
• [ ] ./common/mixin.py
• [ ] ./common/resolve.py

Consider improving the docstring content, not just the formatting.

An opportunity to also tick off #3292?

Ticking off one or more boxes would be a good activity for someone new to making Iris contributions.

Here's how you can test your changes: Contributing to the Documentation

Can we adopt pydocstyle for conformance, at least once we have completed the transition ? Going back to original #3840, and used to check all docstrings was also mentioned in #4689.

I think we can use this both as a pre-commit hook for developers -- which we can implement at once. We can then adopt full CI checking, once we have everything conforming ?

@pp-mo For me, the answer to your question is "yes" and "no". See here.

Personally, I think we should adopt ruff and configure numpy docstring compliance through its pydocstyle support. BTW ruff also has a pre-commit hook, so there are no blockers to our normal dev workflow.

I've already talked to @tkknight about this offline, and he's keen to leverage on-going compliance with pydocstyle checking.

Personally, I think we should adopt ruff and configure numpy docstring compliance through its pydocstyle support.

Well I think that's effectively the same tech under the hood, so how we do it is another discussion, specifically #5254

The main problem as I see it is the effort to get everything "passing" in the first place. I'm just wondering if it's better to do that as a specific project rather than waiting for it to happen piecemeal. I'd suggest that we should get everything passing with "pydocstyle --convention=numpy". I'm not truly sure how comprehensive the checking is, but I've trialled that over in 'ncdata' and at least it doesn't seem horribly onerous to get a sourcefile to pass the check.

Personally, I prefer piecemeal. It's more palatable IMHO.

Anyways, that's how I'm proceeding with this.

And yes, the goal is for pydocstyle --convention=numpy to pass, however we run it.

All files have now been reviewed and updated to ensure they are valid numpydocs.

All future PRs should take the opportunity to improve the docstrings (adding/improving the Parameters section, etc). This is part of the PR checklist (step 6).

https://github.com/SciTools/iris/issues/5625 continues the journey for full adoption of ruff.