I'm writing to share a Sphinx plugin I wrote, which I think makes the documentation for large classes much easier to navigate and understand. The plugin is called `autoclasstoc` and you can find the documentation here:
I wrote this plugin because, while restructured text and Sphinx are great in a lot of ways, I've always been disappointed by the options for documenting classes. `autoclass` is easy to use, but hard to read because all of the methods are just documented one after another with no index at the top. `autosummary` and `autogen` can be used together to create such an index, but they're more difficult to setup, and the index doesn't distinguish nicely between inherited and non-inherited methods.
My plugin is modeled after the way `doxygen` (a popular documentation tool for C++ projects) works. The documentation for each class starts with an index of all it's methods/attributes. Inherited methods are organized by the class they inherit from, and collapsed so they don't distract too much from the methods actually defined in the class itself.
I'm pretty happy with how the plugin turned out, and I hope that other people might find it useful, too. If you decide to give it a try, let me know (either here or, preferably, on Github) if there's anything you'd change. I'm happy to get feedback, because I threw this together pretty quickly and I'm sure there are use-cases I haven't fully considered yet.