sphinx-doc / sphinx-doc/sphinx
Multiple return types aren't hyperlinked
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Using multiple return values, sphinx/napoleon doesn't hyperlink the return types as it does with parameters. I tried with and without explicitly naming the return values.
- OS: Ubuntu 20.04
- Python version: 3.8.10
- Sphinx version: 4.0.2
- Sphinx extensions:
['sphinx.ext.napoleon', 'sphinx.ext.mathjax']
r"""
Parameters
----------
n : int
A positive integer.
B : int, optional
The max divisor in the trial division. The default is `None` which corresponds to :math:`B = \sqrt{n}`.
If :math:`B > \sqrt{n}`, the algorithm will only search up to :math:`\sqrt{n}`, since a factor of :math:`n`
cannot be larger than :math:`\sqrt{n}`.
Returns
-------
list
The discovered prime factors :math:`\{p_1, \dots, p_k\}`.
list
The corresponding prime exponents :math:`\{e_1, \dots, e_k\}`.
int
The residual factor :math:`n_r`.
"""
renders like this

And when naming the return values
r"""
Parameters
----------
n : int
A positive integer.
B : int, optional
The max divisor in the trial division. The default is `None` which corresponds to :math:`B = \sqrt{n}`.
If :math:`B > \sqrt{n}`, the algorithm will only search up to :math:`\sqrt{n}`, since a factor of :math:`n`
cannot be larger than :math:`\sqrt{n}`.
Returns
-------
p : list
The discovered prime factors :math:`\{p_1, \dots, p_k\}`.
e : list
The corresponding prime exponents :math:`\{e_1, \dots, e_k\}`.
n_r : int
The residual factor :math:`n_r`.
"""
it renders like this

However, when using a single return value, the hyperlinks work as expected.

FYI, I am using intershpinx_mapping to link to the python docs, which correctly works for the Parameters section.
# File: conf.py
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'numpy': ('https://numpy.org/doc/stable/', None),
'numba': ('https://numba.pydata.org/numba-doc/latest/', None)
}
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 reproducing the supplied multiple-return-value docstrings with sphinx.ext.napoleon and the intersphinx_mapping shown in conf.py, comparing them with the single-return case. Trace how the Returns section is rendered; done means each return type is hyperlinked consistently with parameter and single-return types.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100