Deepreg: review API reference docs, format for style

[NMontanaBrown]

Subject of the documentation

API reference docs don't have a consistent style, and some arguments are poorly described, or missing. We need a couple of people to review the API docs, reformat for style and make sure everything is clear as we approach release.

If the documentation request is approved, would you be willing to submit a PR? _(Help
can be provided if you need assistance submitting a PR)_

Yes

[mathpluscode]

The argument type for each input/output is also missing.

Emm, btw do we want to stay with the current format?
Google docstring feels to be more popular: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html.

Using https://github.com/dadadel/pyment/, we can easily change all docstring automatically.

[agrimwood]

@acasamitjana @mathpluscode @NMontanaBrown - Having just proof read some of the docs for another issue (#394), I'm thinking we should expand #423 to add a very simple style guide to the contribution section of RTD. Hopefully, this might reduce the amount of post-editing required to keep RTD in good shape.

What do you think of adding 1 or 2 sentences with examples showing basic good practice? I'd be happy to contribute.

[NMontanaBrown]

@acasamitjana @mathpluscode @NMontanaBrown - Having just proof read some of the docs for another issue (#394), I'm thinking we should expand #423 to add a very simple style guide to the contribution section of RTD. Hopefully, this might reduce the amount of post-editing required to keep RTD in good shape.

What do you think of adding 1 or 2 sentences with examples showing basic good practice? I'd be happy to contribute.

Sounds like a plan - consistent formatting via template, don't we love that in this project!
Does it make sense to make the template first and then review docs or how would you go about this @agrimwood ?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[mathpluscode]

I guess this issue is more linked to the format of docstring? Am I right? @NMontanaBrown

[NMontanaBrown]

I guess this issue is more linked to the format of docstring? Am I right? @NMontanaBrown

Yes, as it is sometimes inconsistent across the RTD pages.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[YipengHu]

@NMontanaBrown can you confirm this with @acasamitjana and @agrimwood see if this is on track with the rc1?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.