I am using sphinx to generate my documentation and the autosummary extension takes care of generating little stubs for all classes not explicitly written by myself.
Take the class Foo and assume it has a mixin Base that adds more methods very basic methods that are for storage. They are not private since they might be of use but only to 1% of the users. An also the mixin is present in about all classes that I use. Main point is that the mixin in necessary but documenting it in all classes just clutters the docs and I want to only mention that is uses the Base mixin in the class description, but hide the actual methods and attributes.
Using autodoc I can remove documenting these functions using a custom autodoc-skip-member. This works but only affects the extended documentation of each method, not the listing of the inherited methods in the beginning.
Now autosummary will put all of these in the stubs and does not use any autodoc settings. I hacked the autosummary code to actually do what I want, but this is truly not elegant.
My questions would be:
- Are there other ways to generate these files?
- Are these files meant to be generated everytime the docs are build or is it more a generate the stubs once and edit by hand to your liking approach. That would make sense although I would rather have this automated.
- Can
autosummarybe adapted in a more reusable way to do what I want? - From a programmers point of view: Is it good practice to hide the inherited (even if almost never used) functions at all?
The generated content looks like this
foo.Foo
=======
.. currentmodule:: foo
.. autoclass:: foo
.. automethod:: __init__
.. rubric:: Methods
.. autosummary::
~Foo.method1
~Foo.method2
~Foo.inherited_method_from_Base1 # remove
~Foo.inherited_method_from_Base2 # remove
.. rubric:: Attributes
.. autosummary::
~Foo.attribute1
~Foo.attribute2
~Foo.inherited_attribute_from_Base1 # remove
~Foo.inherited_attribute_from_Base2 # remove
