Docstring style

[reszelaz]

This issue is to poll if there is any interest in the community to use a different docstring style than the reStructuredText (reST) that we currently use.

We were discussing this few days ago with @cpascual while reviewing the legacy custom sphinx extension sardanaextension (similar one is used in taurus).

Also, recently, in #1530 we received a contribution using the numpy style. While #1533 makes it possible to use the numpy style docstings, I think it would be better to agree on one format and use it consistenly along the project.

In this stack overflow thread you can find a review of the available styles (AFAIK, google and numpy are currently the strongest alternatives to the pure reST and they significantly improve the docstring's human readability).

#1534 is an example on how to convet the whole project from one format to the other using pyment.

[cpascual]

Regarding the style, I prefer the google one over the numpy one (it is a little more concise and I prefer not using underscores).

Just one note: we should check if python3's type annotations add something to this discussion

[cpascual]

we should check if python3's type annotations add something to this discussion

... and actually, they do: https://pypi.org/project/sphinx-autodoc-annotation/

[cpascual]

...and both the google and numpy styles also support type annotations out of the box. So basically type annotations can be used instead of defining the parameter and return types, regardless of choosing the basic sphinx style, the google style or the numpy style.

So one could think that this makes it irrelevant for the discussion (since they all support it)... but not really: if we decided to start using type annotations, then the main source of clutter in plain sphinx style (the :type: and :rtype: tags) is gone and there would be less reasons for moving to a non-default style.

[dschick]

I also go for google over numpy, same arguments as @cpascual.

I also see the advantages of type annotation, but I guess this will be alot of work to add all of them to the code and do all the testing...

[jangarrevoet]

I do not have a strong preference besides that the google and numpy versions are way more readable in comparison to rest.

[reszelaz]

With @catunlock we were looking at how to use type annotations and how it could help in writing neat docstrings.
We still need to investigate more on how to use custom Sardana classes as types - we saw that it may cause circular imports problems.