TheAlgorithms / TheAlgorithms/Python
Suggestion: adopt a documentation format for docstring
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 225k
- Forks
- 51.1k
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 156
Description
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:
The doctest will come under the examples section for each of the above format.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the Google Docstring, Numpydoc, and Sphinx formats linked in the issue, including how each handles doctest examples. Review the discussion to determine whether the project has chosen a format. Done means an agreed documentation format and a defined way to apply it across algorithm docstrings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100