Extend Google list sections with more section types
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
The Google list sections recognises currently only "Args", "Raises" and "Attributes" as headers for sections that consist of a definition list. This could be extended to recognise more section headers, similar to what sphinx already does.
The list of sections that sphinx supports is quite extensive, but I'd suggest at least adopting "Keyword Args", "Keyword Arguments", "Yields" and "Examples". The "Yields" header is specifically mentioned by Google as an alternative to "Returns", and I have seen "Examples" mentioned in older versions of the style guide. The keyword arguments are not specified by Google as such, but are widely used.
There are also other list-type sections on the Sphinx list, so implementing as much as possible would improve Sphinx compatibility a lot.
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 locating the Google-style docstring parser's section-header recognition and compare its supported list sections with Sphinx's documented sections. Check how Args, Raises, and Attributes are currently handled, then assess adding Keyword Args, Keyword Arguments, Yields, Examples, and other compatible list sections. Done means the selected headers are recognized consistently and existing behavior remains intact.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100