Documentation: which docstring standard? about esmvaltool

[koldunovn]

I would agree with @bulli92 that the usual Spinx documentation format is rather odd and I personally find it very hard to read. I prefer the Numpy style which is much easier to read.

[bjlittle]

In the recent 2nd coding workshop at the DLR (totally awesome btw) I opted for the numpy style for the backend.regrid module ... works for me.

Note quite sure how that renders in Sphinx, but if it's good enough for numpy ...

[bulli92]

We used the 'numpy style' also for the documentation of the python code used in the diagnostics. Compiles like charm with sphinx. Only requires (on some machines) a sphinx plugin. Anything else is straight forward. Thus I suggest, we use the numpy convention for all further coding.

…

On 5/22/17 7:44 PM, Bill Little wrote: In the recent 2nd coding workshop at the DLR (totally awesome btw) I opted for the numpy style for the backend.regrid <https://github.com/ESMValGroup/ESMValTool/blob/REFACTORING_backend/backend/regrid.py> module ... works for me. Note quite sure how that renders in Sphinx, but if it's good enough for numpy ... — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#50 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACt0C-KMtOwI4HoB2reHc3r6xMfxnX6yks5r8cl8gaJpZM4Mk4hz>.

[bouweandela]

It looks like there is agreement that the numpy docstring standard should be used for python code. Perhaps this could be added to the documentation (section "7.8 Documentation of source code" of ESMValTool_Users_Guide.pdf) and then this issue can be closed.

[mattiarighi]

In the v2 doc there is no section on Documentation of source code at the moment, where else could we add the statement about numpy docstrings?

[bouweandela]

Maybe we should add a section on code quality and documentation, or link to CONTRIBUTING.md and add more information there.