sphinx-doc / sphinx-doc/sphinx

Docstring section Yield type doesn't hyperlink in napoleon

Open
#10,982 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

Not sure if this is a new bug or a regression, see #8004. I'm reporting this bug as specific to the Yield docstring section of the sphinx.ext.napoleon extension for Google style docstrings, (perhaps #10134 is also related but it seems NumPy specific.)

So whatever the relevant configurations of napoleon or autodoc you use -I tried this with every combination I could think of- it seems the type of the Yield docstring section is never hyperlinked.

How to Reproduce

A minimal conf.py (I think it's better in this case to include all the relevant configurations with explicit values):

import os
import sys

sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'src')))

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

templates_path = ['_templates']
exclude_patterns = []

html_theme = 'alabaster'
html_static_path = ['_static']

toc_object_entries = False
add_module_names = False
add_function_parentheses = True
smartquotes = False

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

autodoc_typehints_format = 'short'
autodoc_typehints_description_target = 'all'
autodoc_preserve_defaults = True
autodoc_class_signature = 'mixed'
autodoc_docstring_signature = False

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

A simple example module my_package.my_module.py

from typing import Iterator


class MyClass:

    def test_method(self, my_arg) -> Iterator[int]:
        """Test docstring

        Args:
            my_arg (int): text.
        Yields:
            Iterator[int]: text
        """
        yield 1

A minimal my.rst

title this
==========

.. module:: my_package.my_module

    .. autoclass:: MyClass
        :members:

A screenshot showing the problem:

github_yield

Environment Information
Platform:              win32; (Windows-10-10.0.19041-SP0)
Python version:        3.9.0 (tags/v3.9.0:9cf6752, Oct  5 2020, 15:34:40) [MSC v .1927 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        5.3.0
Docutils version:      0.17.1
Jinja2 version:        3.1.2
Sphinx extensions
['sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.intersphinx']

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

Reproduce the issue with the provided conf.py, my_package.my_module.py, and my.rst using autodoc and napoleon. Start by tracing how the Google-style Yields section processes Iterator[int], then add a regression test that verifies the yield type is hyperlinked in the generated documentation.

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.