Docstrings should follow the numpy docstring guide. Read more about it Docstring formatting and type hints. In ArviZ docs, docstrings consit of five main sections, i.e.,
Examples Extended summary is strongly encouraged and references is required when relevant in order to cite the papers proposing or explaining the algorithms that are implemented. All other sections can also be used when convenient.
While adding description of parameters, examples, etc, it is important to add references to external libraries and ArviZ. Docstrings follow the same guide for adding references as the other docs. For adding references to external libraries functions and objects, see Reference external libraries. For referencing ArviZ objects, follow Referencing ArviZ objects.
In ArviZ docs, we have a lot of interconnected functions both within the library and with external libraries and it can take a lot of time to search for the related functions. It is cruical to add the See Also section to save users time. For adding the See Also docstring section, you just need to add the function name. Sphinx will automatically add links to other ArviZ objects and functions listed in the See Also section.
For example, let’s add
plot_ppc() in the See Also section.
See Also -------- hdi : Calculate highest density interval (HDI) of array for given probability. plot_ppc : plot for posterior/prior predictive checks.
All the kwargs parameters in plots modules are passed to the matplotlib or bokeh functions. While writing their description, the functions to which they are being passed must be mentioned. In order to check or add those functions, the process is the same for all the kwargs arguments. Let’s read the step-by-step guide for
backend_kwargs as an example, here.