-
-
Notifications
You must be signed in to change notification settings - Fork 44k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Suggestion: adopt a documentation format for docstring #6252
Comments
+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. |
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.
Isn't this already being enforced by the bot? Or, are you referring to something else? |
Sticking with the easiest / most lenient one would be straightforward, but let's see if there are other concerns.
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. |
Can I work on this @poyea @dhruvmanila ?
|
How is this completed? @cclauss |
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. |
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. |
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. |
But what tool are we going to use to generate the docs? Does Google provide such a tool that we can use? |
Usually the tools are independent of the format. They're decoupled. So, we choose the format and then we choose the tool. There's |
As the number of algorithms are increasing, it might make sense to adopt a single documentation format for docstrings. Following are existing currently:
There are editor extensions which help in generating the docstring based on the chosen format like:
The doctest will come under the examples section for each of the above format.
The text was updated successfully, but these errors were encountered: