Suggestion: adopt a documentation format for docstring

[dhruvmanila]

As the number of algorithms are increasing, it might make sense to adopt a single documentation format for docstrings. Following are existing currently:

• Google Docstring: https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings
• Numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
• Sphinx: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html

There are editor extensions which help in generating the docstring based on the chosen format like:

• VSCode: https://github.com/NilsJPWerner/autoDocstring
• Neovim: https://github.com/danymat/neogen

The doctest will come under the examples section for each of the above format.

[poyea]

+1. Do we have any hints / metrics on which one we should use? I've seen some Sphinx style recently.

A sightly longer term goal may be to use the generated documentation site instead of DIRECTORY.md as the main source of the file list. However, we might want to focus on enforce the docstring style first.

[dhruvmanila]

Do we have any hints / metrics on which one we should use?

We already are using type hints everywhere and they will be improved as we develop, so the argument types will automatically be taken from there. I find Google Docstring to be the simplest while Sphinx provide backlinks to other functions/methods/class and Numpydoc is verbose with wide adoption in the Data Science community.

We can sit on it for a few days, take a look around in the community and see which benefits us the most. Our end goal will be to use this to generate the documentation which can be added to our main website.

However, we might want to focus on enforce the doctest style first.

Isn't this already being enforced by the bot? Or, are you referring to something else?

[poyea]

I find Google Docstring to be the simplest while Sphinx provide backlinks to other functions/methods/class and Numpydoc is verbose with wide adoption in the Data Science community.

Sticking with the easiest / most lenient one would be straightforward, but let's see if there are other concerns.

Isn't this already being enforced by the bot? Or, are you referring to something else?

It was a typo - I mean docstring style, but here I'm not sure if there's a way we only allow a specific docstring style for a file. And this way we can know ow many files are not compliant. Otherwise, I think we can simply make it a convention and grow it from there.

[ksharma20]

Can I work on this @poyea @dhruvmanila ?
If what I am understanding is correct ! Then basically,

• I need to download a vscode extension like autoDocstring .
• Then change Docstring of every Algorithm (function) with a docstring format style like Sphinx
• And Remove the Doctests to Put them somewhere Down below ? as Examples

If there is something that I misunderstood, then please consider Coreecting me and breifing me out on How it can be done ?!
I am actually quite new to contributions

[dhruvmanila]

How is this completed? @cclauss

[dhruvmanila]

I'm leaning more towards Google format as they're simple and contains all the necessary information. The type hints in the docstring would be optional as they're already provided in the function signature.

[cclauss]

My experience with https://pypi.org/project/sphinx-autodoc-typehints suggests that it can generate solid docs for function and class parameters and return types just by reading their typed signatures. The thing that contributors will need to add are function/class descriptions and parameter and return type descriptions.

[dhruvmanila]

All format can generate documentation. In your case, the docstring was already written in sphinx format, so it was easy to adopt the mentioned plugin.

We have the benefit of starting from scratch so we can choose the format now.

[cclauss]

But what tool are we going to use to generate the docs? Does Google provide such a tool that we can use?

[dhruvmanila]

Usually the tools are independent of the format. They're decoupled. So, we choose the format and then we choose the tool. There's mkdocstrings which is a plugin to mkdocs which can generate from all the mentioned formats (google, numpy, sphinx) - https://mkdocstrings.github.io/python/usage/. We can explore other tools as well, but this is the first one which comes to my mind.

[cclauss]

@priya-sundaram-dev wrote #15081 (comment)

2022-era discussion with no champion. I'd either commit to one (numpydoc reads best with doctests) and close, or close as stale — it shouldn't linger undecided.