sphinx-doc / sphinx-doc/sphinx

autodoc: Allow overloaded functions to have different docstrings

Open
#7,787 13 comments 28 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

If would be great if sphinx could emit all of the docstrings for something like:

from typing import overload

@overload
def my_bytes(n: int):
    """ construct an empty array of n bytes """

@overload
def my_bytes(s: bytes):
    """ copy an existing bytes-like object """

def my_bytes(b):
    """ Some common docstring """
    return bytes(b)

As of the fix to #3610, autodoc emits:

.. function:: my_bytes(n: int)
              my_bytes(s: bytes)
    Some common docstring

but does not extract the first two docstrings.

Perhaps one reasonable option would be to emit

.. function:: my_bytes(n: int)
    construct an empty array of n bytes

    Some common docstring
.. function:: my_bytes(s: bytes)
    copy an existing bytes-like object

    Some common docstring

although this doesn't scale to .. class particularly well.

Another choice would be to render numbers next to the overloads (in the style of cppreference), and then refer to them in the text. In its most minimal form, that would be:

.. function:: my_bytes(n: int)
              my_bytes(s: bytes)
    :number-overloads:

    1. construct an empty array of n bytes
    2. copy an existing bytes-like object

    Some common docstring

but perhaps new directives or roles could be introduced to render that better:

.. function:: my_bytes(n: int)
              my_bytes(s: bytes)

    .. overloadref::1  # presence of these makes the numbers appear as needed.
        construct an empty array of n bytes
    .. overloadref::2
        copy an existing bytes-like object

    Some common docstring

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 reviewing the existing autodoc overload handling introduced by issue #3610 and the examples in this report. Compare the proposed rendering approaches for overloaded docstrings, including how they would apply to classes. Done means an agreed behavior is implemented and verified for the shown overloaded-function case.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.