osdir.com


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Sphinx plugin to make easier-to-navigate class documentation


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:

https://autoclasstoc.readthedocs.io/en/latest/

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.

-Kale