sphinx-doc / sphinx-doc/sphinx
autodoc: Allow overloaded functions to have different docstrings
Nobody has claimed this yet.
- 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
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 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