-
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Open
Labels
Description
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 fails, attribute docs have been removed
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