Chilipp / autodocsumm

Extending your autodoc API docs with a summary
Apache License 2.0
48 stars 14 forks source link

Surprising effect on attribute documentation #95

Open jenshnielsen opened 4 months ago

jenshnielsen commented 4 months ago

I have observed that when I document a class with autodocsumm it will result in the documentation containing not only the documented attributes of the class but also inherited attributes and none documented attributes with a type annotation. Removing the :autosummary: directive makes the issue go away which is why I assume the issue is related to autodocsumm.

For example, consider the following classes.

class Foo:
    """
    Foo is a class that does not inherit from any thing
    """

    classattr: str = "MyClassAttr"
    """
    This is a class attribute
    """

    def __init__(self):
        self.instance_attr: str = "MyInstanceAttr"
        """
        This is an instance attribute
        """

        self.typed_instance_attr: str = "MyTypedAttrNoDocs"

class Bar(Foo):
    """
    Bar is a class that inherits from Foo
    """

    def __init__(self):
        self.other_instance_attr: str = "MyOtherInstanceAttr"
        """
        This is annother instance attribute
        """

        super().__init__()

and the following rst file.

API
===

This is the debugproject API docs

.. automodule:: debugproject
    :autosummary:
    :no-inherited-members:

This result is the documentation below for Bar

image

Here I would not expect instance_attr and typed_instance_attr to be included in the docs but they are documented inline but not in the table provided by autodocsumm.

See the full example in https://github.com/jenshnielsen/debugproject/tree/autodocsumm_attrs