1

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Jay Parthasarthy
  • 327
  • 1
  • 4
  • 11
  • Similar to https://stackoverflow.com/q/30856279/407651 and https://stackoverflow.com/q/15115514/407651 – mzjn Dec 04 '19 at 18:32
  • This question concerns apidoc, not really Sphinx itself. Edited to remove the corrolary concern. – Jay Parthasarthy Dec 04 '19 at 22:57
  • You would have to edit the output from sphinx-apidoc by hand (change `.. automodule:: x.y.z` to `.. automodule:: x`). I don't think there is any setting that does this automatically. – mzjn Dec 05 '19 at 05:48

1 Answers1

1

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
   ...
Jay Parthasarthy
  • 327
  • 1
  • 4
  • 11