Iris: 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 https://github.com/SciTools/iris/pull/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 :+1: 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 :+1: 👍 👍 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.

[rcomer]

• Improve the docstrings as we port

That could potentially incorporate #3292, which is currently in the 3.1 milestone/project.

[tkknight]

If we agree to use numpy docstrings, we can review the default napolean settings: https://github.com/SciTools/iris/blob/master/docs/iris/src/conf.py#L135-L147 to ensure it fits our needs.

We could also look into automating checks for non numpy docstrings so we can check for compliance over time.

[bjlittle]

Although this all seems like a lot of work, if we just divvy it up between a whole bunch of core devs, and people iterate on individual modules so that we don't tread on each others toes, we could easily swarm on this and nail it pretty quickly.

That would be lovely :smile:

[pp-mo]

automating checks for non numpy docstrings

I rather assumed it already did that.
Will it accept anything without complaint then, or will it detect and warn of (some) non-compliant docstrings ?

[tkknight]

hi @pp-mo,

Napolean was introduced to also allow numpy docstrings, as some we being pulled in from outside of the Iris docs. This was enabled via https://github.com/SciTools/iris/blob/master/docs/iris/src/conf.py#L136. See the full PR https://github.com/SciTools/iris/pull/3871.

A quick tests shows that if I set napoleon_google_docstring = False (currently is True) it appears to make no difference. It will still parse all existing google docstrings, I was hoping it would flag up all google docstrings so we can easily check for conformance.

However, if any are badly formatted docstrings it will flag as a warning, and as all sphinx build warnings are now configured to be promoted to errors, it will fail the build (this is to ensure no warnings creep in).