Adopt numpy docstrings

[tkknight]

📚 Documentation

We should adopt the NumPy docstrings for Iris over the current Google Style docstrings.

There is a sphinx extension that allows both to be supported when creating the API documentation, named Napolean. This would allow the Iris codebase to gradually move to numpy docstrings and avoid a big bang approach.

We could also:

• Improve the docstrings as we port
• Update the developers guide on the documentation to state the intent

Can the @SciTools/iris-devs can agree this? (btw, I'm not proposing this goes into Iris 3.0.0)

[bouweandela]

To make it easier to have an opinion on this, could you shortly describe why the numpy style is better than the google style?

[pp-mo]

BTW the current style, as described in https://scitools-iris.readthedocs.io/en/latest/developers_guide/documenting/docstrings.html , is not in fact simply "google style". I think we designed it to our own best needs.
The biggest difference, I think, is our using separate "Args" and "Kwargs" sections (instead of labelling individual args as "optional" in the description). This is of course Python-specific. In future, I personally would like to start using keyword-only parameters for some things, as I think this really enhances code transparency in some cases. I don't know how we will be representing that in docstrings, perhaps it is just obvious from the signature (but so is the arg/kwarg distinction).

FWIW I personally prefer the more google-like style, simply because it uses less vertical space, which makes it more readable in the code files.

[tkknight]

See #3871. This PR enables the napolean extensions to allow both Google and Numpy docstrings. It does not force adoption of numpy - but it could with a change to the config in conf.py.

[bjlittle]

Personally, I think the iris doc-strings, in general, are a bit of mess.

Unless there is a hint of rigour or standardisation, which there isn't at the moment, we've ended up with quite a wide ranging combination of "google style" (and I use that in the loosest possible terms) doc-strings.

After the documentation, users will hit the doc-strings to get details on functionality, and it's really is a bit of a lottery regarding the quality and format that they get.

In general, I think it's high time that we had some doc-string hygiene, so it makes sense to me that if we're revisiting the content and quality of doc-strings, that we also address the format of the doc-strings.

I think that we could argue either way for google style vs numpy style, but that fact that I can follow a numpy docstring guide, off the bat, wins hands down for me - there's a standard there to follow, and we don't have to reinvent the wheel, and it plugs into napolean just fine.

So I'm 👍 for numpy style, which personally, I find a lot clearer and it renders just fine in readthedocs. So I'd happily iterate on slowing migrating iris doc strings across - I can see the end user benefit for the effort, particularly when it comes to hinting at the dtype of arguments

[pp-mo]

Agree with all the above, except I marginally prefer google style for compactness, as I already said !
If this pushes us to conform to a single standard, and stick to it, I'm 👍 👍 👍 for that !

[bjlittle]

@SciTools/developers Are you guys happy for me to add this issue to the backlog for 3.1 ?

[rcomer]

I have no objection to the proposal but I'm glad I'm not the one who would have to implement it!

I must admit I've never gone looking for guidelines on how the docstrings should look. I just look at what else is in the module and try to make my new bit consistent. That approach would obviously be problematic if we are part way through porting...

[pp-mo]

add this issue to the backlog for 3.1 ?

I may have overdone the enthusiasm slightly.
But I don't think this would be too hard to do, really. It just needs prioritising.