Docstring format decision and advertisement

[zklaus]

Checklist

• I added a descriptive title
• I searched open reports and couldn't find a duplicate

What happened?

Currently, many things in the code base lack docstrings. Where they are present, there is a mix of pure Sphinx style docs (ex1), sort of free form (ex2), Google style (ex3), and Numpy style (ex4).
The latter two styles are supported thanks to our use of the Napoleon extension, which has been part of the sphinx distribution since version 1.3 released in 2014.

While homogenizing the entire code base would be a lot of work, agreeing on a single style moving forward and documenting this choice in the contribution guidelines would make it easier for developers to familiarize themselves with a single style of docstrings and to include them more consistently in new code.

Among the available styles, Google and Numpy are the two natural choices; by propensity in the code base, Google is the more common with ~61 uses of the signature Args: in the code base versus a single use of the Numpy equivalent Parameters.

I propose to adopt the Google style for docstrings as the standard for conda projects.

Additional Context

No response

[zklaus]

I was curious to get a better feel for what is used in the wider python ecosystem, so I had a look at the top projects (according to number of stars) on github with language: python in the search. I discarded many projects that where things like "online speech cloning" or "the worst input strings for db apps" and here is what I came away with for projects with 43k stars or more:

Google style (4)

• Keras
• Pytorch
• rich
• Tensorflow

Numpy style (2)

• Pandas
• scikit-learn

Sphinx (3)

• Ansible
• Flask
• requests

Other (3)

• cpython
• Django
• FastAPI

Other ecosystems

I arbitrarily chose some projects that I think are indispensable from the scientific python ecosystem:

Numpy style (4)

• Dask
• Matplotlib
• Numpy
• Scipy

Though of course this is not an independent selection.