numpydoc adoption tick list

[tkknight]

📚 Documentation

GOAL: Improve the docstring content and ensure numpydocs formatting.

Related to #5637.

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 Clarify laziness status of all iris functions #3292

How to Test usinf ruff (preferred)

Install ruff into your iris-dev conda environment via:

• pip install ruff

Temporarily enable the ruff checker by commenting out this line: https://github.com/SciTools/iris/blob/main/.ruff.toml#L30 Once all the repo the source is compliant this ignore rule can be removed.

You can then run the checker via (running against time.py in this example):

• ruff time.py

How to Test (not preferred)

Unless we find something better we can use pydocstyle. Install into your iris-dev conda environment via:

• pip install pydocstyle

You can then run the docstring checker via (running against time.py in this example):

• pydocstyle --convention=numpy --add-ignore=D105 time.py

We can use the numpy convention otherwise there maybe conflicts in the errors codes (fix one and and the other triggers and vice versa).

Proposed additional error codes to ignore:

• D105 - Missing docstring in magic method

Hit List

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 (@tkknight DOCS: Numpydocs3 #5635)
• ./_concatenate.py (@tkknight DOCS: numpydocs 5 #5715)
• ./_constraints.py (@tkknight DOCS: Numpydocs3 #5635)
• ./_merge.py (@tkknight DOCS: numpydocs 5 #5715)
• ./_data_manager.py (@tkknight DOCS: numpydocs 5 #5715)
• ./_deprecation.py (@tkknight)
• ./_lazy_data.py (@tkknight DOCS: numpydocs 5 #5715)
• ./aux_factory.py (@tkknight DOCS: Numpydocs3 #5635)
• ./analysis/init.py (@tkknight DOCS: Numpydocs3 #5635)
• ./analysis/_area_weighted.py (@tkknight DOCS: numpydocs 5 #5715)
• ./analysis/_grid_angles.py (@tkknight DOCS: numpydocs 4 #5711)
• ./analysis/_interpolation.py (@tkknight DOCS: numpydocs 5 #5715)
• ./analysis/_regrid.py (@tkknight DOCS: numpydocs 5 #5715)
• ./analysis/_scipy_interpolate.py (@tkknight)
• ./analysis/calculus.py (@tkknight DOCS: Numpydocs3 #5635)
• ./analysis/cartography.py (@tkknight DOCS: numpydocs 5 #5715)
• ./analysis/geometry.py (@tkknight DOCS: numpydocs 5 #5715)
• ./analysis/maths.py (@tkknight DOCS: numpydocs 5 #5715)
• ./analysis/stats.py (@rcomer Re-write pearsonr to use Resolve #5638, DOCS: numpydocs 5 #5715)
• ./analysis/trajectory.py (@tkknight DOCS: numpydocs 5 #5715)
• ./util.py (@tkknight DOCS: numpydocs 5 #5715)
• ./config.py (@tkknight DOCS: Numpydocs1 #5578, DOCS: numpydocs 5 #5715)
• ./coord_categorisation.py (@tkknight DOCS: numpydocs 6 #5718)
• ./coord_systems.py (@tkknight DOCS: numpydocs 6 #5718)
• ./coords.py (@tkknight DOCS: numpydocs 6 #5718)
• ./cube.py (@tkknight DOCS: numpydocs 6 #5718)
• ./exceptions.py (@tkknight)
• ./experimental/init.py (@tkknight)
• ./experimental/animate.py (@tkknight)
• ./experimental/raster.py (@tkknight)
• ./experimental/regrid.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/regrid_conservative.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/representation.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/stratify.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/ugrid/init.py (@tkknight)
• ./experimental/ugrid/cf.py (@tkknight)
• ./experimental/ugrid/load.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/ugrid/mesh.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/ugrid/metadata.py (@tkknight)
• ./experimental/ugrid/save.py (@tkknight DOCS: numpydocs 6 #5718)
• ./experimental/ugrid/utils.py (@tkknight)
• ./fileformats/init.py (@tkknight)
• ./fileformats/_ff.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/_ff_cross_references.py (@tkknight)
• ./fileformats/_pp_lbproc_pairs.py (@tkknight)
• ./fileformats/_structured_array_identification.py (@tkknight)
• ./fileformats/abf.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/cf.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/dot.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/name.py (@tkknight)
• ./fileformats/name_loaders.py (@tkknight)
• ./fileformats/netcdf/init.py (@tkknight DOCS: Numpydocs1 #5578)
• ./fileformats/netcdf/_dask_locks.py (@tkknight DOCS: Numpydocs1 #5578)
• ./fileformats/netcdf/_thread_safe_nc.py (@tkknight DOCS: Numpydocs1 #5578)
• ./fileformats/netcdf/loader.py (@tkknight DOCS: Numpydocs1 #5578, DOCS: numpydocs 7 #5720)
• ./fileformats/netcdf/saver.py (@tkknight DOCS: Numpydocs1 #5578, DOCS: numpydocs 7 #5720)
• ./fileformats/nimrod.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/nimrod_load_rules.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/pp.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/pp_load_rules.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/pp_save_rules.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/rules.py (@tkknight)
• ./fileformats/um/init.py (@tkknight)
• ./fileformats/um/_fast_load.py (@tkknight)
• ./fileformats/um/_fast_load_structured_fields.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/um/_ff_replacement.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/um/_optimal_array_structuring.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/um_cf_map.py (@tkknight)
• ./fileformats/_nc_load_rules/init.py (@tkknight)
• ./fileformats/_nc_load_rules/actions.py (@tkknight DOCS: numpydocs 7 #5720)
• ./fileformats/_nc_load_rules/engine.py (@tkknight)
• ./fileformats/_nc_load_rules/helpers.py (@tkknight DOCS: numpydocs 7 #5720)
• ./io/init.py (@tkknight DOCS: Numpydocs1 #5578)
• ./io/format_picker.py (@tkknight DOCS: Numpydocs1 #5578)
• ./iterate.py
• ./palette.py
• ./pandas.py (@tkknight DOCS: numpydocs 8 #5722)
• ./plot.py (@tkknight DOCS: numpydocs 8 #5722)
• ./quickplot.py (@tkknight DOCS: numpydocs 8 #5722)
• ./symbols.py
• ./time.py (@tkknight DOCS: Numpydocs1 #5578)
• ./_representation/init.py
• ./_representation/cube_printout.py (@tkknight DOCS: numpydocs 8 #5722)
• ./_representation/cube_summary.py
• ./std_names.py
  • N/A as this file is auto-generated via python setup.py std_names and on build/install.
• ./common/init.py (@bjlittle)
• ./common/lenient.py (@bjlittle) (@tkknight DOCS: numpydocs 8 #5722)
• ./common/metadata.py (@bjlittle) (@tkknight DOCS: numpydocs 8 #5722)
• ./common/mixin.py (@bjlittle)
• ./common/resolve.py (@bjlittle) (@tkknight DOCS: numpydocs 8 #5722)
• ./_version.py

[rcomer]

Consider improving the docstring content, not just the formatting.

An opportunity to also tick off #3292?

[trexfeathers]

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

[pp-mo]

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 ?

[bjlittle]

@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.

[pp-mo]

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.

[bjlittle]

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.

[tkknight]

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).

#5625 continues the journey for full adoption of ruff.