mitmproxy / mitmproxy/pdoc

Extend Google list sections with more section types

Open
#466 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.