Template docstrings

[ThomSerg]

A proposal reference on the docstring style.

I tried cleaning up the model.py docstrings a bit, following the google docstring style, to use this file as a reference (model.py seemed to have the most consistent docstrings already).

Alternative docstring styles are

• numpydoc
• reST style
• javadoc style

(see here for some examples)
In my opinion, the google style is the most readable. But open to other proposals.

A decision which still needs to be made, regards the use of backticks. Single backticks render as italic text, double render as inline code. In some of our docstrings we use single where double would actually be more appropriate. There is an option in sphinx to render both as inline code, fixing the rendering without needing to change all out backtick use. But as included in this example template, it can still be useful to be able to make a distinction between the two. E.g. .pickle file format is referenced somewhere. We want to highlight it, but not make it an inline code. So single backtick makes it italic.

---

So a proposal:

• use google-style docstrings
• use backlinks whenever possible (e.g. :func:`SolverLookup.solvernames() <cpmpy.solvers.utils.SolverLookup.solvernames>
• if possible include type hints for the arguments and the return value
• single backticks to highlight a piece of text (e.g. a concept like a file type), use double backticks for inline code snippets (use codeblocks .. code-block:: python when not inline)
• for default values, it seems like adding (default: ...) at the end of the argument description has already been used quite consistently, so we could stick with that style

Will add these guidelines to the wiki (and update them with any feedback provided here)