Make docstrings to be nice with pydoc
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.7k
- Forks
- 408
- Avg merge
- 2d 57m
- Merged PRs (30d)
- 7
Description
In some doc-strings we use formatting rules specific to Sphinx, but which make the interactive help (pydoc) to look bad.
This issue is about:
- defining how we should write some recurrent stuff, like documenting input parameters and return values.
- rewrite the doc-strings so they look fine on pydoc, even if that means losing some features with Sphinx, like cross references.
Note. If we had the resources, we would do like Python does, and document things twice: once in the doc-strings and a feature rich version in the rst files. But in any case the doc-strings must be usable with pydoc, so lets start with that.
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
No files, tests, or entry points are named. Start by inventorying the project's docstrings and comparing their rendered output in pydoc with Sphinx conventions; done means agreed formatting rules for recurring parameters and return values, plus rewritten docstrings that remain usable in pydoc.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100