Standardisation of docstrings

[jhabriel]

I have a few questions/comments regarding docstrings that might be interesting to answer/address.

1. According to https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google, we need to use Args instead of Parameters. Would this be the standard in PorePy as well?
2. My understanding is that typings is always enforce (or at least highly encouraged) in all classes/methods. Following the same reference, this implies that one does not need to specify (again) the type in the docstring. Are we going to follow this rule?
3. In many places, we hint the size of an array in parenthesis next to the argument, i.e., var (nd x pts): description. I'm not sure if sphinx will be happy with this. Do you know @vlipovac? In any case, if we are doing this, we might want to standardise whether the shape hint goes in parenthesis next to the argument or rather in the description of the argument itself.
4. Perhaps a less critical point is how exactly an argument is described (which might also be related to 3). To be precise, it would be beneficial to standardise this. My suggestion is (now based on @vlipovac reply) to use the following format

"""
var (TypeVar): Description of var. Default value (if applicable).
    Shape of var (if applicable).
    Other notes/comments about var.
"""

Keeping a structure like this one could be extremely useful.

I will most likely keep extending the list, but these are the questions I can think of right now.

[IvarStefansson]

1. Yes.
2. I agree that we do not need to specify it twice.

[vlipovac]

1. Might even be necessary, since the google style docs apparently are only able to interpret Args:

2. To my knowing, Sphinx works only with the docstrings (extracting __doc__), not with typing. So without the type in the docstring, the generated documentation will have no hints about the type. Plus the type annotation in the docstring goes hand in hand with inter-doc-linking, which would be a great feature.

3. Good point, I need to test this. (the numpy style allows you to put anything there, according to their style guide. For the google style I do not recall any specification)

[jhabriel]

1. Then, we settled for Args.
2. This is important, then we have to keep the type hint in the docstring to please sphinx.
3. See my suggestion in point 4 of Standardisation of docstrings #677 (comment).

[vlipovac]

I would put vital information such as default values and fixed dimensions before the description or anything else, as a kind of quick user summary.
Same goes for an admissible set of values for a keyword argument.
Google does not mention this, but numpy does https://numpydoc.readthedocs.io/en/latest/format.html#parameters

[jhabriel]

This is also a good point. I'm a bit more inclined towards first reading the description of the argument, and then the other information. After all, you have to know "what is" before knowing "what is permissible" or "what is the default". These are details, but as a said, we might want to standardise these types of things.

And you're right, Google does not mention this explicitly, but if you check def module_level_function(param1, param2=None, *args, **kwargs): from https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google, it prioritises the description first.

Thoughts about this @IvarStefansson @OmarDuran ?

[keileg]

A agree with @vlipovac in putting dimensions and default values before a description; more often than not, I know what the parameter is, but don't know how to use it (e.g., should the array be transposed, can I use the default value).

[vlipovac]

Update:
The standardisation of docstrings is currently being implemented and tested.
I refer to the branch docs.
To inspect the current docs and the standard go to the folder docs/ and run make html
The output pages can be found in the subdirectory called builds.