DOCS: Numpydocs1

[tkknight]

🚀 Pull Request

Description

Progressing numpydoc strings adoption, #4721.

Notes

• I have ensure numpydoc style where possible by refactoring existing docstring, I have not labelled every single type etc, this is an improvement not a 100% perfect docstring.
• Where appropriate I have added # noqa: D102 or # noqa: D102 (see error codes desc). This comment will skip the checks for the subsequent line.
• A single line summary is needed on functions. I used the first part of the summary for this so there maybe a little duplication but I think that is ok
• In lib/iris/fileformats/netcdf/saver.py there are a couple of very long links, these would render with a horizontal scroll which looks weird, so I used a text and a url instead.

pydocstyle test output

No errors/warnings raised. Commands used:

pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/config.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/fileformats/netcdf/__init__.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/fileformats/netcdf/_dask_locks.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/fileformats/netcdf/_thread_safe_nc.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/fileformats/netcdf/loader.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/fileformats/netcdf/saver.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/io/__init__.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/io/format_picker.py 
pydocstyle --convention=numpy --add-ignore=D105 ../lib/iris/time.py 

Links to current and new API docs

Note, some files are private so are not rendered in the docs.

• current, new: lib/iris/config.py
• current, new: lib/iris/fileformats/netcdf/__init__.py
• lib/iris/fileformats/netcdf/_dask_locks.py
• lib/iris/fileformats/netcdf/_thread_safe_nc.py
• current, new: lib/iris/fileformats/netcdf/loader.py
• current, new: lib/iris/fileformats/netcdf/saver.py
• current, new: lib/iris/io/__init__.py
• current, new: lib/iris/io/format_picker.py
• current, new: lib/iris/time.py

---

Consult Iris pull request check list

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (54ad9be) 89.68% compared to head (0a47aa2) 89.68%.
Report is 2 commits behind head on main.

❗ Current head 0a47aa2 differs from pull request most recent head 10d4214. Consider uploading reports for the commit 10d4214 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5578   +/-   ##
=======================================
  Coverage   89.68%   89.68%           
=======================================
  Files          90       90           
  Lines       22818    22818           
  Branches     5446     5446           
=======================================
  Hits        20465    20465           
  Misses       1619     1619           
  Partials      734      734           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bjlittle]

@tkknight Awesome, thanks for taking this on and chipping away at it - it's so important to have compliance here and there are years of mixed styling in the iris docs 🙀

Only one question ... going forwards it would be good to be consistent with the spacing after the color and the variable when there is a type in the docstring i.e., var : type instead of var: type

I prefer spacing around the color, and the numpydoc states to have the spacing, although ruff doesn't enforce this (to my knowledge) although pydocstyle might (I've not checked) ... it would be ideal if this was an automated check going forwards though.

Otherwise LGTM (given your stated caveats, which I totally agree with) 👍

[tkknight]

Review actions 506968f