I'm looking for an automatic API generation tool for use with python projects. I'd like to have (in more-or-less order of priority)

  1. Method descriptions in docstrings per python standard practice
  2. In a class's doc, list superclass methods that this class can call
  3. The tool itself should have documentation.
  4. Support ReStructuredText or MarkDown
  5. The tool itself should have readable documentation
  6. The resulting html should look nice
  7. Support embedding LaTeX
  8. Support embedding graphics

1, 2 and 3 are essential
6, 7, and 8 are not

As far as I can tell:

Doxygen fails #1 and #4
Sphinx-autodoc fails #2 and #6 (but I can probably find/write a theme that passes)
pydoc, and pydoctor appear to fail #3 (and may fail elsewhere, but without docs I can't try them)
Sphinx and pdoc fail #5 (but I can work through the docs with difficulty)

I can't understand why Sphinx autodoc does not list superclass methods in a class's doc. Note that :inherited-members: does not produce this. It produces a link to the superclass. One has to climb up the inheritance tree to find all callable methods. IMO, at best this is difficult, and at worst produces incomplete docs.

It would also be nice if the tool plays well with Sphinx, because Sphinx seems to be great for everything except auto generation of API docs.

Is there any tool that passes 1, 2, and 3?
I can't find one.

  • perhaps a local installation of github.com/rtfd/readthedocs.org -- I haven't confirmed all of your requirements hence a comment rather than an answer – d3vid Jun 28 '16 at 14:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.