Description
The numpydoc format guide says this about default values:
Optional keyword parameters have default values, which are
displayed as part of the function signature. They can also be
detailed in the description::Description of parameter `x` (the default is -1, which implies summation over all axes).When a parameter can only assume one of a fixed set of values,
those values can be listed in braces, with the default appearing first::order : {'C', 'F', 'A'} Description of `order`.
so default values can be documented as
- part of the signature
- mentioned in the parameter description
- for a fixed set of values, the first value of that set
pandas and later xarray decided to instead document default values as part of the type specification, but with a slightly different syntax:
pandas does something like
Parameters
----------
a : int, default 0
while xarray uses a additional colon:
Parameters
----------
a : int, default: 0
(also, the example set for the numpydoc_xref_ignore contains 'default')
In order to fix the numerous broken references when building the xarray documentation using napoleon I have been working on sphinx-doc/sphinx#7690 to preprocess the parameter type specification. However, including support for xarray's default value syntax was rejected because the sphinx maintainer didn't want to include a unofficial extension to the format (the PR is still pending).
So here's my question: is any of those two formats "official"? If not, could we make one of them (or both?) official?