astropy / astropy/sphinx-automodapi

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

Open
#66 10 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
67
Forks
48
Avg merge
11h 52m
Merged PRs (30d)
1

Description

If I document instance variables as follows

```python
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.)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reproducing the class example with automodapi and :include-all-objects:, then inspect how instance variables, properties, and class variables are collected for the attributes section. Investigate the undocumented autoinstanceattribute keyword and verify that documented instance variables appear in the attributes section and can be referenced with :py:obj:.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.