The way type annotation for instance attribute is shown depends on the way it's documented in

Open
#9,586 0 comments 0 reactions 0 assignees View on GitHub

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

type:bug
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

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.

More from sphinx-doc/sphinx

All issues in sphinx-doc/sphinx

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.