sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.46k stars 2.1k forks source link

Autodoc: Missing documentation when importing decorator from other file #11750

Open AVHopp opened 10 months ago

AVHopp commented 10 months ago

Describe the bug

Hello everyone :)

In one of my projects, I observed that the behavior for using decorators depends on whether the function that you use for decorating is contained in the same or another file. I get the following output for the code provided below:

image

As you see, there is no entry for the class using the imported decorator, although both the classes and the decorators are identical (except their name). I would have expected that both classes will be documented in the same way.

How to Reproduce

conf.py:

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

index.rst:

.. automodule:: test
    :members:
    :undoc-members:

.. automodule:: utils
    :members:
    :undoc-members:

test.py:

from utils import my_imported_decorator

def mydecorator(decorated_class):
    """Docstring for original decorator"""

    class DecoratorClass(decorated_class):
        def __init__(self) -> None:
            decorated_class.__init__()

    return DecoratorClass

@mydecorator
class DecoratedClass:
    """My first decorated class."""

    def __init__(self) -> None:
        self.attribute = 5

@my_imported_decorator
class ImportedDecoratedClass:
    """My second decorated class."""

    def __init__(self) -> None:
        self.attribute = 5

utils.py:

def my_imported_decorator(decorated_class):
    """Docstring for imported decorator."""

    class ImportedDecoratorClass(decorated_class):
        def __init__(self) -> None:
            decorated_class.__init__()
            self.test = "test"

    return ImportedDecoratorClass

Environment Information

Platform:              darwin; (macOS-14.1-arm64-arm-64bit)
Python version:        3.9.18 (main, Sep 11 2023, 08:25:10) 
[Clang 14.0.6 ])
Python implementation: CPython
Sphinx version:        7.2.3
Docutils version:      0.18.1
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

["sphinx.ext.autodoc"]

Additional context

No response

picnixz commented 9 months ago

We probably incorrectly detect the decorator usage. I'm sorry but I don't have time to investigate this so it will be stalled for a long time probably...