readthedocs / readthedocs/sphinx-autoapi
Allow finer-grained control over display of inherited members
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 494
- Forks
- 147
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
When we generate documentation for classes, we have two situations:
- We wrote a base class with various attributes and methods that we want exposed to the user, and we would like the inherited members to be displayed in the derived classes.
- We derived a class from Exception or Enum or some other generic class (not necessarily in the python standard library) and thus inherit a heap of methods that are not of interest to the user; we would like to suppress display of inherited members.
If a given project contains only one of these categories, we can select inherited-members or not as appropriate. But if we have both situations in the same project, there does not seem to be a way we can get the desired behaviour.
Ideally I would like to be able to set something on the class definition (perhaps in the class docstring?) that would control whether this class showed inherited members. (Perhaps this could even work recursively up the inheritance graph, so that deriving from a class that didn't show its inherited members I could show members inherited from that class but not its superclasses.)
Sadly autoapi-skip-member does not provide enough information (as far as I can tell) to inspect the (docstring of the) class that the object is a member of. It does at least provide obj.inherited, which is a key piece of information.
I suppose I could maintain a list of classes that did or did not want their inherited members documented, and perhaps I could use the fully qualified name to check whether objects in autoapi-skip-member were members of one of these classes. Having to maintain this list separately from the classes being documented seems error-prone.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the inherited-members setting and the autoapi-skip-member hook described in the issue, including the obj.inherited information it exposes. Define how per-class configuration should interact with inherited classes and recursive inheritance, then confirm that both exposing selected inherited members and suppressing unwanted generic members can be documented and tested.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100