Switch docstring style to Google style?

[jluethi]

As discussed at today's call, we should consider (e.g. for the next maintenance week) whether we should switch the docstring style in fractal-tasks-core to the google style (see here)

Benefits: More in line with other Fractal packages like fractal-server

Things that would need to be done: Update all docstrings Update documentation building

[tcompa]

For the record, we found (with @ychiucco) that https://rr-.github.io/docstring_parser/#compose does a reasonable job in automatically converting a docstring to a different style.

[tcompa]

A first version of this PR is in now in-place, see #473. For the moment:

• Docstrings are now more similar to Google style (for functions and classes, although I think we are still non-compliant with the class-attribute descriptions).
• Sphinx parses these docstrings, thanks to the napoleon extension.

To review:

• [x] Check that documentation is fully equivalent to the previous one. This is in progress. The two versions look fairly similar, but I need to review them more carefully.
• [x] Check that JSON Schemas are fully equivalent to the previous ones. This is done: up to a minor change that I introduced by hand, the new JSON Schemas are identical to the previous ones, meaning that the dev tools were sufficiently general and did not depend on a specific docstring style.
• (low priority) Review the class-attributes docstring style, to check whether we could comply with Google style without creating issues to JSON-Schema-generation tools. EDIT: moved to #474

What we achieve / where could we go:

• We are moving to code base which is more homogeneous with the other Fractal repositories.
• We are moving to a more pleasant dev experience in writing/reading docstrings (at least in my view).
• We are not so tightly bound to sphinx any more, and we could envision moving to mkdocs. This would likely:
  • Make it easier to start using markdown in docstrings (to be reviewed: (a) would this be the right way to produce formatted data for fractal-web? (2) Would moving to mkdocs actually make this easier?).
  • Bring the dev tools to build fractal-tasks-core docs in-line with the fractal-server ones, to avoid some duplication. (*)

(*) Note: the CLI client docs currently rely on https://sphinx-argparse.readthedocs.io, and then we would need to find an alternative in order to move all repositories to mkdocs. Maybe https://github.com/chriskiehl/ArgDoc? TBD.

---

Given the current situation, I wouldn't push for mkdocs as a priority. When/if we realize that this would be helpful for using markdown, we can reconsider.

[tcompa]

• Check that documentation is fully equivalent to the previous one. This is in progress. The two versions look fairly similar, but I need to review them more carefully.

I went through all modules and visually compared the old/new docs, and they are identical (apart from minor fixes that were introduced on purpose).