16

We don't want to be maintaining documentation as well as the source code, which is evolving rapidly at the moment, yet Sphinx seems to require a frustrating amount of setup and configuration. (We just need some basic API docs.) Is there not a single command you can run inside a python project that will just iterate over all of the packages, modules, classes and functions generating documentation as HTML?

The sphinx-apidoc splats stuff into a directory, and after modifying the conf.py to have our packages in the sys.path we can run "make html", but it only lists packages and modules without documenting any classes or functions.

Thanks!

mzjn
  • 48,958
  • 13
  • 128
  • 248
rosejn
  • 849
  • 1
  • 7
  • 9

1 Answers1

19

The sphinx-apidoc tool will autogenerate stubs for your modules, which might be what you want.

Instructions

  • Make sure the autodoc module was enabled during Sphinx configuration.

    extensions = ['sphinx.ext.autodoc']

    within Sphinx's conf.py should do the trick.

  • Make sure conf.py adjusts sys.path accordingly (see the comments at lines 16-19 in the file).

    sys.path.insert(0, os.path.abspath('/my/source/lives/here'))

  • Run sphinx-apidoc to generate skeletons.

    sphinx-apidoc -o /my/docs/live/here /my/source/lives/here

  • Rebuild the docs. If all goes well, you shouldn't get the following sort of warning:

    mymodule.rst:4: WARNING: autodoc can't import/find module 'mymodule'

  • Your module RSTs should now be populated.

AKX
  • 152,115
  • 15
  • 115
  • 172
  • 2
    I tried that, but the generated html just has links to empty modules with no functions or classes in them. – rosejn Feb 26 '13 at 14:49
  • I elaborated a little on the process in the answer. HTH – AKX Feb 27 '13 at 13:22
  • I had to first pass in output path, for the sphinx-apidoc command – Nevermore Jun 11 '16 at 13:59
  • 2
    Do I have to run sphinx-apidoc every time I create a new file so it creates a skeleton? I am used to Doxygen where it handles auto documentation on the fly. – c3cris Jun 25 '16 at 23:22