Link to correct documentation page which describes the docstrings style

[ashwinvis]

In the section In-code documentation — How to document your research software documentation it reads

Read more: https://peps.python.org/pep-0257/

although the PEP does not specify any particular format or convention for parsing Python docstrings. The same problem exists for other languages. It could be a good idea to add one more link for further reading:

• Python:
  • https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
  • https://numpydoc.readthedocs.io/en/latest/format.html
• Julia: the current link is good enough, but if needed https://docs.julialang.org/en/v1/stdlib/Markdown/#markdown_stdlib can be added as well
• R: is it https://roxygen2.r-lib.org/articles/rd.html ?
• Fortran and C++: https://www.doxygen.nl/manual/docblocks.html
• Rust: is it https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html ?

[frankier]

This seems like a good call, except for this section is before the Sphinx section, so while it might be appropriate to mention docstring conventions, their automatic parsing by API documentation tools is probably premature. So I'm not quite sure about the best way to action this at the moment.

[ashwinvis]

It is not premature. On the contrary, it is very wide-spread to use autodoc and autosummary for automatic parsing.

Moreover the convention is in some ways tool-agnostic. See https://mkdocstrings.github.io/python/ which has no dependency on Sphinx, but:

Multiple docstring-styles support: common support for Google-style, Numpydoc-style, and Sphinx-style docstrings. See Griffe's documentation on docstrings support.

[ashwinvis]

Aha... sorry, I misunderstood what you meant by premature. Premature in terms of learners' perspective and not in terms of the library. Now I get what you meant

[ashwinvis]

The intention with this issue was to give proper references on how to write docstrings. PEP 257 is not a good reference.