Enforce google docstrings

[quaquel]

This PR enforces Google docstrings in ruff, enables parsing of Google docstrings in building the documentation for readthedocs, and (the real work) fixes all documentation to be in line with the Google docstring. While going through all the docstrings, I have made various minor modifications to improve wording.

I have used noqa D103 in quite a few places (e.g., outdated parts of the code, various tests, solara parts that I don't fully know). This means that some parts don't have a docstring yet.

[Corvince]

Awesome effort! That is something that has bugged me for some time and finally some effort to fix this!

I think instead of mixing and matching our own way of writing docstrings we should strive to fully adapt a style guide and I think the numpy style guide would be most appropriate and I see this most used in the scientific community.

Note that with a clear structure of the docstring format the visual representation on for example readthedocs can become a separate thought. Take for example psygnal: It uses numpy docstring format at least for the parameters (link), but renders completely different on readthedocs (with bulleted lists, links to type definitions, etc.)

[quaquel]

I think instead of mixing and matching our own way of writing docstrings we should strive to fully adapt a style guide and I think the numpy style guide would be most appropriate and I see this most used in the scientific community.

Judging the current docstrings, it seems closests to the google docstring standard. So I sort of implicitly assumed that as the standard while working on MESA. I personally also prefer numpy. It would take a few hours to rewrite everything to numpy if all maintainers agree to use that.

[EwoutH]

Awesome, always love documentation improvements!

Also agree on the style guide. Especially to get things as bulleted lists correct consistently.

[Corvince]

It would take a few hours to rewrite everything to numpy if all maintainers agree to use that.

There are actually several docstring converters you can find on pypi. Not sure how good they work

[EwoutH]

I would support using the NumPy Style guide for docstring formatting and numpydoc for Sphinx / Readthedocs rendering. Especially if we can enforce it in CI (preferably pre-commit).

[Corvince]

I'll see what I can do about the solara stuff, most docstrings there are also way outdated since my refactoring!

Since this PR here is basically unreviewable due to its size, I guess I will do that in a separate PR. So for the time being you just add some noqa D to solara, is this your understanding as well?

[quaquel]

Since this PR here is basically unreviewable due to its size, I guess I will do that in a separate PR. So for the time being you just add some noqa D to solara, is this your understanding as well?

Yes that makes the most sense and is what I have done now.

[quaquel]

If there are no objections, I plan to merge this PR at the close of business today. All tests and ruff stuff passes. I have checked readthedocs also and this looks much cleaner now.

[EwoutH]

Skimmed through it, looks great in general!

[rht]

I have a class of comments related to the non-specific noqa comments. Shouldn't they be noqa: D103? But this is not blocking the merge of this PR, and can be done in a subsequent PR, since this PR is already too big.

[quaquel]

I have a class of comments related to the non-specific noqa comments. Shouldn't they be noqa: D103? But this is not blocking the merge of this PR, and can be done in a subsequent PR, since this PR is already too big.

I'll make a pass to make the noqa's specific. Will also be easier in the future to find them.

[rht]

I think the ':' is necessary, # noqa: D103, but haven't tested.

[quaquel]

Thanks for pointing this out. I have fixed it everywhere. This noqa stuff is quite new to me.

[Corvince]

Over 1000 changed lines! Awesome work @quaquel , thanks for doing this