sphinx-doc / sphinx-doc/sphinx

Multiple return types aren't hyperlinked

Open
#9,394 15 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
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

image

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

image

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

image

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.