The way type annotation for instance attribute is shown depends on the way it's documented in
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Clone the linked sphinx-issue-9585 reproduction, install Sphinx, and run docs/make html to compare the Point, Square, and Rectangle renderings. Start by tracing sphinx.ext.autodoc handling of annotated attributes documented in class docstrings versus with #: comments. Done means the two documentation styles render consistently, or the supported configuration and its behavior are clearly established.
Written by the indexing model from the issue text.
Description
Describe the bug
The document is rendered differently depending on whether I use #: before the attribute or the class docstring to document the attribute:
from typing import Optional
class Point:
"""
A class representing a point.
Attributes:
x: Position X.
y: Position Y.
"""
x: int
y: int
class Square:
"""A class representing a square figure."""
#: Square's start position (top-left corner).
start: Point
#: Square width.
width: int
#: Square height.
height: int
@property
def end(self) -> Point:
"""Square's end position (bottom-right corner)."""
return Point(self.start.x + self.width, self.start.y + self.height)
class Rectangle:
"""
A class representing a square figure.
Attributes:
start: Rectangle's start position (top-left corner).
width: Rectangle width.
height: Rectangle width.
"""
start: Point
width: int
height: int
@property
def end(self) -> Point:
"""Rectangle's end position (bottom-right corner)."""
return Point(self.start.x + self.width, self.start.y + self.height)
How to Reproduce
$ git clone https://github.com/jack1142/sphinx-issue-9585
$ cd sphinx-issue-9585
$ pip install sphinx
$ cd docs
$ make html
$ # open _build/html/index.html and see the issue
Expected behavior
I expected both of these cases to be rendered the same. Not sure in which way (I think I prefer to use the type field, as in the way the Rectangle is shown in, and I think it should also apply to the property in there even though it doesn't here for some reason), preferably it would be configurable.
Your project
https://github.com/jack1142/sphinx-issue-9585
(sic! I reused the repository from a different issue)
Screenshots
Here's a link to the generated docs:
https://sphinx-issue-9585.readthedocs.io/en/latest/
(sic! I reused the repository from a different issue)
OS
Windows 10, Ubuntu 18.04
Python version
3.7, 3.8, 3.9
Sphinx version
4.1.2
Sphinx extensions
sphinx.ext.autodoc
Extra tools
No response
Additional context
This might be related to #7582 but none of the comments there seem to mention the Python type annotations, they all only mention Sphinx's type annotation so I feel this might be a different issue.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from sphinx-doc/sphinx
-
type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
sphinx-doc/sphinx#14699 ·
-
type:bug type:tests
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
sphinx-doc/sphinx#14678 ·
-
type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
sphinx-doc/sphinx#14659 ·
-
autodoc: IndexError formatting signature for callable data object with annotated class variable Openextensions:autodoc type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
sphinx-doc/sphinx#14576 · 2 comments ·
-
extensions:autodoc extensions:autosummary type:bug type:docs
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
sphinx-doc/sphinx#14555 · 2 comments ·
All issues in sphinx-doc/sphinx
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
bancolombia/sentinel#23 ·
-
test md OpenCI
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
integration:quickjs org:external priority:backlog topic:code-interpreter topic:middleware type:feature
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
langchain-ai/deepagents#6450 ·
-
bug client
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100