Skip to content

Autodoc does not support * in type annotations #13853

@Horrih

Description

@Horrih

Describe the bug

Hello to all,

Thank you for your work maintaining sphinx.

Bug description

I have encountered an issue where sphinx autodoc fails to parse docstrings starting with #: when the type contains a * symbol. We use this pattern in our codebase to provide reusable annotations sets (otherwise every single type can take several lines). This trick works fine with cpython and pydantic.

Sphinx still detects the fields, however the autodoc fails to parse the class attributes docstrings when we use this syntax

Code triggering the bug

from dataclasses import dataclass
import typing

a = 5
b = "yo"
MyAnnotations = (a, b)


@dataclass
class MyClass:
    """MyClass description."""

    #: Some attribute
    some_attribute: bool

    #: This works
    working_annotation: typing.Annotated[int, a, b]

    #: This does not work, it will remove the docstring of other attributes of this class
    failed_annotation: typing.Annotated[int, *MyAnnotations]

What sphinx renders

When it works
Image

When it fails, attribute docs have been removed
Image

How to Reproduce

Minimal build :

uv run sphinx-build -M html . _build

Here is the conf.py :

import sys

sys.path.insert(0, ".")
extensions = [
    "sphinx.ext.autodoc",
]
exclude_patterns = [".venv"]

Here is the index.rst

.. automodule:: myclass
   :members:
   :show-inheritance:
   :undoc-members:

Here is the myclass.py

from dataclasses import dataclass
import typing

a = 5
b = "yo"
MyAnnotations = (a, b)


@dataclass
class MyClass:
    """MyClass description."""

    #: Some attribute
    some_attribute: bool

    #: This works
    working_annotation: typing.Annotated[int, a, b]

    #: This does not work, uncomment and it will remove the docstring of other attributes
    # failed_annotation: typing.Annotated[int, *MyAnnotations]

Environment Information

Platform:              linux; (Linux-5.14.0-503.22.1.el9_5.x86_64-x86_64-with-glibc2.34)
Python version:        3.12.9 (main, Jun 20 2025, 00:00:00) [GCC 11.5.0 20240719 (Red Hat 11.5.0-5)])
Python implementation: CPython
Sphinx version:        8.2.3
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

extensions = [
    "sphinx.ext.autodoc",
]

Additional context

No error/exception in the logs

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions