syntax to document default values

[keewis]

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?

[rossbar]

So here's my question: is any of those two formats "official"? If not, could we make one of them (or both?) official?

I'm not sure I understand the question. AFAICT both of those formats should work fine with numpydoc.

[keewis]

that's true, but neither of them is mentioned in the docstring guide. So I guess I should rephrase that and ask if that guide or the implementation are the official spec of the format.

Anyway, that might have answered my question. I'll check with the maintainer and report back.

[keewis]

okay, so the maintainer of napoleon will accept supporting both, but isn't too happy about the format not being part of the docstring guide (since that seems to be the official spec of the format). Would you accept a PR that adds both as an option to that document?

[larsoner]

Seems reasonable to me