BTW ruff has a docstring linter, a colleague is using it to great effect

@JoeZiminski you're going to get us to ruff eventually :)

Just one small point @chrishalcrow and maybe @JoeZiminski can comment on if ruff would be able to handle this tunability.

We had discussed a while back trying to move everything to a modified numpy docstring. So we use the numpy docstring sections (Parameters, Returns, Notes, etc), but for arguments we don't use the optional tag when a default is supplied (that never made sense to me because it is not optional to the function, just optional to the user) and we do arg: type, default: value.

If you think that is a bad style we can discuss as part of this project to see if fully switching over to pure numpy is better. For further example see the style guide in the docstring conventions section.

I think that optional should be used when the value is None (e.g. value=None) That is, the parameter does not have to be specified. Default is used when there is default value that is not None.

This policy seems to be the most consistent with both python.typing Optional and with numpy docstring specification:
https://docs.python.org/3/library/typing.html#typing.Optional
https://numpydoc.readthedocs.io/en/latest/format.html

Hello,

Just been preparing some stuff for this. A couple of things:

Ruff only applies a subset of numpydoc standards. In particular it doesn't implement ones about parameters, which I'm keen to implement. But it's so good for lots of other things, thanks for mentioning it @JoeZiminski !

Both of your suggestions are valid with numpydoc standards (see Section 4 of https://numpydoc.readthedocs.io/en/latest/format.html#parameters, you can either do the optional thing or supply a default). Here's a real world example:

def generate_noise(noise_level=15.0, spatial_decay=None):
    """
    Return a recording which is just noise.

    Parameters
    ==========
    noise_level : float | np.array | tuple, default: 15.0
        a description.
    spatial_decay : float, optional
        a description.
    """

Opinions? @zm711 do you agree with the optional? @h-mayorquin does it look ok? I'll ask a few more people before the hackathon!

EDIT: also numpydoc prefers "or" over "|". Thoughts?

I think both or and | are fine. No opinion on that one. I usually use auto generation so I hope I can set it up to that. I don't think that it matters enough to grant extra work on our side.

As for the real example, yes, that's exactly how I read the documentation that it should be. This is consistent with typing.Optional semantics. Having optional for cases when the default is None (the most common case of typing.Optional) and having default and making the value explicit when the you are choosing.

There is the degenerate case when you are choosing, None is an option but the default is something else that I think we should try to avoid anyway. But we should discuss that case separateley and don't let an edge case dictate common policy.

The last option is consistent with numpy docstrings and is also consistent with python typing semantics where optional means that it can be None.