Return type does not get linked if napoleon_use_rtype = True

[SwampFalc]

Describe the bug If I set napoleon_use_rtype to False, I get a nice link to the type of the return value.

However, if I change napoleon_use_rtype to True, because I much prefer the single-line format, there is no more link. Unless I manually add backticks

I find this to be wholly inconsistent with the rest of Napoleon and therefore consider it to be a bug.

To Reproduce Steps to reproduce the behavior:

Write a basic napoleon "Returns" statement:

        Returns:
            bool: success or failure.

Set napoleon_use_rtype to False, run sphinx-build. You get a linked but separate "Rtype" field.

Set napoleon_use_rtype to True, run sphinx-build. The bool type is inlined with your text, but is no longer linked.

Expected behavior Whether I want to have an inline return type, or a separated field, should have no impact on whether or not the type gets linked.

Environment info

• Sphinx version: 3.2.1
• Sphinx extensions: sphinx.ext.napoleon

[ain-soph]

It's been 1 year. Any progress on this?

And btw, @SwampFalc , in your original post, I think maybe you inverted/misplaced True and False?
napoleon_use_rtype = False leads to the single-line format, while False leads to the separate ReturnType field.

[tk0miya]

If my understanding is correct, napoleon_use_rtype works as documented. It was documented to generate the following returns field (starting with emphasized type).

:returns: *bool* -- True if successful, False otherwise

refs: https://www.sphinx-doc.org/ja/master/usage/extensions/napoleon.html#confval-napoleon_use_rtype

I can understand it would be better if it's linked. But I feel it's a breaking change...

[ain-soph]

I can understand it would be better if it's linked. But I feel it's a breaking change...

That makes sense. So maybe just keep as it is now.

[ain-soph]

@tk0miya Could you please kindly explain how :rtype: bool would generate the link for bool? Is it sth similar to put :any:`bool` there?

If that's the case, maybe a simple solution is to change napoleon output to :any:`bool` rather than *bool*.

[aabmets]

@ain-soph @tk0miya You need to use intersphinx, which turns all native types of Python into links to the Python documentation.

[ain-soph]

@aabmets It's a different issue.

For example, how to make the return type of my method be linked?
https://ain-soph.github.io/alpsplot/figure.html#alpsplot.figure.Figure.lineplot
Corresponding codes in https://github.com/ain-soph/alpsplot/blob/main/alpsplot/figure.py#L471-L575

I've configured the intersphinx in my conf.py, but the napolean extension will simply output text rather than codes with link (like what it does in returntype field). The current workaround might be to modify the docstring to explicitly add the link using :any: role, but that's too hacky and I want to keep my codes clean and standard.

The only solution is to make napolean generate links. But as maintainer claims, it's a breaking change and he refused to do that.

[aabmets]

@ain-soph In source code:

def cx_one_point(ind1: Individual, ind2: Individual) -> Mates:
    """
    Executes a one-point crossover on the two individuals,
    who are modified in place. The resulting individuals
    will have the respective length of the other.

    :param ind1: The first individual.
    :param ind2: The second individual.
    :return: Two mated individuals.

    :type ind1: :ref:`Individual <datatypes>`
    :type ind2: :ref:`Individual <datatypes>`
    :rtype: :ref:`Mates <datatypes>`
    """

conf.py:

extensions = [
    'sphinx_rtd_theme',
    'sphinx.ext.intersphinx',
    'sphinx.ext.napoleon',
    'sphinx.ext.autodoc'
]

autodoc_typehints = 'description'
autodoc_typehints_description_target = 'documented'
autodoc_typehints_format = 'short'
autodoc_preserve_defaults = True
autodoc_warningiserror = True
autodoc_inherit_docstrings = True
autoclass_content = "both"
autodoc_class_signature = 'mixed'
autodoc_member_order = 'bysource'
autodoc_default_options = {}
autodoc_docstring_signature = True
autodoc_type_aliases = {}

napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_preprocess_types = False
napoleon_attr_annotations = True
napoleon_type_aliases = None

Sphinx output:

[ain-soph]

@aabmets You are using individual Return type. That works with link for sure.

I'm assuming the compact case napoleon_use_rtype = False

[ain-soph]

If my understanding is correct, napoleon_use_rtype works as documented. It was documented to generate the following returns field (starting with emphasized type).

:returns: *bool* -- True if successful, False otherwise

refs: https://www.sphinx-doc.org/ja/master/usage/extensions/napoleon.html#confval-napoleon_use_rtype

I can understand it would be better if it's linked. But I feel it's a breaking change...

@tk0miya Since it's a breaking change, would you consider it in sphinx 6.0 ?

[aabmets]

@ain-soph I gotchu fam :grin:

In source code:

def cx_one_point(ind1: Individual, ind2: Individual) -> Mates:
    """
    Executes a one-point crossover on the two individuals,
    who are modified in place. The resulting individuals
    will have the respective length of the other.

    Args:
        ind1 (:ref:`Individual <datatypes>`): The first individual.
        ind2 (:ref:`Individual <datatypes>`): The second individual.
    Returns:
        :ref:`Mates <datatypes>` - Two mated individuals.
    """

In conf.py:

autodoc_typehints = 'none'
napoleon_use_rtype = False

Sphinx output:

[aabmets]

@ain-soph It's quite a homogay hack, but there is no alternative afaik.