UX: move to Google style for docstrings about paramak HOT 4 CLOSED

I think we originally chose the native Sphinx style docstrings in reStructured format to avoid the use of an additional Sphinx dependancy (Napoleon).

I agree that the Google style looks nicer.

We are always keen to make improvements and take on advice.

When we started using Sphinx we just wanted something that works easily. Now that we have been using Sphinx for a while we are more comfortable in adding dependencies to the workflow so I think it is a good time to reconsider that original decision.

What I would be interested to know is can we have a mixture of Google and reStructured in the same project. If so then I imagine that we can transition gradually to the Google style

It is not the most exciting part of the project but I can see the benefits.

Readthedocs currently builds on just the develop branch so we might have to tinker with those settings as well to try this.

We use VScode to autogenerate the reStructured docstrings so that is not really an win for either option.

It also might be worth explaining why Google docstrings instead of PEP0257 or Numpy but I can see it is nicer than the reStructured

What are your thoughts @billingsley-john

from paramak.

@shimwell I'm not sure if Napoleon 🇫🇷 🍷 🧀 is handled like an actual dependency though. But @billingsley-john can certifies I don't understand much about how Sphinx works 😉

from paramak.

I will test whether a mixture Google and reStructured can be used in the same project. As mentioned by @shimwell, this would facilitate the gradual movement to Google-style over time

from paramak.

Docs now support both Google and reStructured/Sphinx styles. Added in #99

from paramak.