search

mantle-convection-constrained / terratools

Tools to read, analyse and visualise models written by the TERRA mantle convection code
https://terratools.readthedocs.io/en/latest/
MIT License
7 stars 5 forks source link

Docstring consistency #31

Closed anowacki closed 1 year ago

anowacki commented 2 years ago

We should use a consistent docstring format that can be automatically made into web pages for reference purposes. I have generally used ReST-formatted docstring in the Sphinx style, but I haven't used cross-referencing and other features. Likewise, lots of other code doesn't use this format.

We should decide on a format and ensure it's used consistently.

andreww commented 1 year ago

Once we know how we autogenerate documentation we'll know what the limitations are. @bobmyhill will look at how to enable autodoc for tetta_model.py as a starting point

bobmyhill commented 1 year ago

Autodoc added by #45 through #50. Looks like the sphinx style works nicely: https://terratools.readthedocs.io/en/latest/reference/terratools/terra_model/

anowacki commented 1 year ago

Great, thanks Bob! Let's stick with the Sphynx style you and I have used from now on, then (linked to above.

It looks like it would be good for terra_model.py to add types, and for lookup_tables.py to switch to this format (@eejwa and @jamespanton93).

I think we can close this when all the current docstrings are the same then.

eejwa commented 1 year ago

Okay, no problem. I can change the docstrings in lookup_tables.py.

bobmyhill commented 1 year ago

@anowacki, @eejwa I've edited the docstrings throughout the code so that they render reasonably. But some of the docstrings could do with some more work to make it clear what each function does, the types of each input and output parameter, etc.

anowacki commented 1 year ago

98 mentions this now, but of course consistency will need to be watched for in PRs. Possibly adding a mention to .github/PULL_REQUEST_TEMPLATE.md may be useful.