How to generate Python documentation using Sphinx with zero configuration?

Question

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!

AKX · Accepted Answer · 2013-02-27 13:22:43Z

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.

edited Feb 27, 2013 at 13:22

answered Feb 26, 2013 at 14:16

AKX

171k16 gold badges147 silver badges229 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

rosejn Over a year ago

I tried that, but the generated html just has links to empty modules with no functions or classes in them.

AKX Over a year ago

I elaborated a little on the process in the answer. HTH

Nevermore Over a year ago

I had to first pass in output path, for the sphinx-apidoc command

c3cris Over a year ago

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.

Collectives™ on Stack Overflow

How to generate Python documentation using Sphinx with zero configuration?

1 Answer 1

Instructions

4 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Instructions

4 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related