sphinx-doc / sphinx-doc/sphinx

Add an `autodoc_typehints_return` option

Open
#13,489 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:proposal
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Hi there,

I think it would be cool to explicitly tell autodoc not to document the return type automatically when autodoc_typehints in {"description", "both"}.

Indeed, it is generally ugly when documenting a tuple return type such as the following.

def foo(): -> tuple[int, int]:
    """Foooo.

    Returns
    -------
    a: int
        Bar.
    b: int
        Baz.
    """
    return 0, 1

Note that the napoleon option napoleon_use_rtype = False does not work, and also, one cannot use the autodoc-process-docstring event since the return type specification seems to be added after it...

Options could be "all", "none", "undocumented" for example.

All the best!
Élie.

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 tracing autodoc_typehints and the autodoc-process-docstring event, checking where return types are added relative to that event; napoleon_use_rtype is noted as ineffective here. Define the option semantics, such as all, none, or undocumented, and verify that tuple-return documentation does not duplicate documented fields while other return types follow the selected behavior.

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
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.