:include-all-objects: does not include instance variables.

[mjstahlberg]

If I document instance variables as follows

class A:
    def __init__(self):
        self.a = None
        """Documented instance variable."""

then they do not show up in the attributes section (or anywhere at all) of the class documentation pages generated by automodapi, even with :include-all-objects:.

It would be ideal to find them in the attributes section, together with the properties and the class variables, as the user is not supposed to be able to distinguish between those three types (after all property's job is to make the user think they are dealing with variables while really they are using functions).

Note that there seems to be an undocumented autoinstanceattribute keyword that might be useful.

(If I use the alternative approach of putting :ivar a: Documented instance variable. in the class' docstring then they appear as part of the class documentation in an info field list but they cannot be referenced, i.e. :py:obj:'a' does not find its target.)

[mjstahlberg]

I also found that :include-all-objects: does not include any reference to inner classes.

[appukuttan-shailesh]

@Viech : Did you find any solution or workaround to this problem?

[mjstahlberg]

I switched to AutoAPI. :slightly_frowning_face:

[appukuttan-shailesh]

Just to be sure, are you referring to: autoapi (https://github.com/carlos-jenkins/autoapi) or sphinx-autoapi (https://github.com/readthedocs/sphinx-autoapi)?

Does it do a good job of documenting both class and instance attributes?

[mjstahlberg]

The first one. It does document instance attributes; for example it documents

    def __init__(self, […], info={}, […]):
        […]
        self.info = info
        """Additional information provided by the solver."""

as

info = None
    Additional information provided by the solver.

which is not ideal given the misleading None, but good enough for me. I don't think we use class attributes anywhere but define any constants inside modules, and for this it works well.

I now remember that the selling point for AutoAPI was that it uses Jinja templates for the pages generated for each module, which makes it highly configurable, in particular when it comes to embedding the API docs in a broader documentation and in a scenario where you have both modules and subpackages and want them to be documented in a similar style. Inside the Jinja templates you would just use a regular Sphinx .. autoclass:: with options of your choice. At first I did not like their requirement that you have to define __all__ or __api__ with each module but I came to the conclusion that this is just necessary to allow control over when and what imported symbols to document.

[appukuttan-shailesh]

Thanks a lot @Viech for the detailed response. The use of Jinja templates certainly offers a lot of flexibility. I am tempted to try it out sometime soon.

[Nodd]

This is the blocking issue for me, it makes class documentation unusable. :(

[pllim]

Will #169 fix this too?

[Nodd]

Sadly, no. Instance variables require another kind of introspection, since they don't appear in the class definition.

[Nodd]

This could be a solution : https://github.com/sphinx-doc/sphinx/pull/9146

use sphinx.ext.autodoc.get_class_members instead of dir(obj) to discover class members and find instance attributes