Docstring update guidelines

Guidelines for updating the Parameter and return section of the API docs. Below we highlight some of the changes (based on common bad practices in our current docs), however, the general guidelines we follow (and that the highlights below aim to follow) is the numpydoc style. In addition, if something isn't clear or isn't specified in the numpydoc guide, you can check the matplotlib or pandas docstring guides.

Now on to the highlighted good/bad practices:

• The colon between an argument name and it's type must be both preceded and followed by a space.

• Type hints should go in the call signature, not in the docstring. Optional[Union[str, int]] is not adequate for a docstring, it should be str or int, optional. Type hints target machines, docstrings target humans.

• Optional parameters must be indicated with , optional or , default <value>.

  • If the default value is of the documented type and used directly, using default instead of optional is preferred. However, if the default value depends on other parameters or is a placeholder (i.e. it is very common to use None for kwarg type arguments) then optional should be used, explaining the default in the description.

• In type descriptions. We have several aliases available to keep raw docstrings short and clear while generating still a nice html page with all the correct links. Again, here we highlight some aliases, to check the complete list see the numpydoc_xref_aliases dict in the conf.py file.

  Highlighted aliases:

  • InferenceData: change things like az.InferenceData, arviz.InferenceData or inference data to this.
  • Labeller: change labeller, labeller instance and similars to this

  Built-in types. Links also work automatically with existing types (things like str, int, float...) but for this to work the exact type needs to be used which might not be always clear. Here are some examples to look out for:

  • Plurals: All types in the parameter type description should be in singular. That is, if the type is dict or float we need to use exactly that, not dicts or float even if the type is list of dict which would be read as "list of dictionaries".
  • object: This is the correct type for parameters whose type can be anything. Things like obj need to be updated to this.