Search code examples
pythonpython-sphinxautodocsphinx-apidoc

How to use Sphinx apidoc to only document Python classes that are imported in __init__.py?

So currently I'm using apidoc to generate .rst files for my documentation and then using autodoc on them. The issue is that my package separates code into many different files which leads to this nested mess (my toctree has max depth 4):

Welcome to (package)'s documentation!
Contents:
- (package)
    - (package) package
        - subpackages
            - package.subpackage1 subpackage
            - ...
        - submodules
            - package.submodule1 module
- module contents

We import all relevant classes to the base __init__.py of the package.

As an example: we have a public class package.submodule1.SubModule1Class. As a package user, I can import the class by doing from package import SubModule1Class).

I want to automatically generate documentation from all classes we've imported in this __init__.py in a flat hierarchy, like so:

Welcome to (package)'s documentation!
Contents:
- SubModuleClass1
- SubModuleClass2
- SubModuleClass3
...

What configuration settings on apidoc can I use to achieve this goal state? I've tried a variety of things but nothing even resembles this.

Solution

  • The solution I came up with was to use Autosummary which wasn't exactly what I wanted but did good enough. I had to import all top-level classes to my index.rst:

    .. toctree::
   :hidden:

   self

.. autosummary::
   :toctree: stubs
   :nosignatures:

   package.MyClass1
   package.MyClass2
   ...