sphinx-apidoc usage - multiple source python directories

Question

So I have my python source files in two different directories:-

e.g.

~/work/myproject
~/.virtualenvs/myproject

How do I use sphinx-apidoc to look in both directories recursively to generate my reST files?

Obviously,

sphinx-apidoc -o docs/source ~/work/myproject

works perfectly fine but when I attempt to run

sphinx-apidoc -o docs/source ~/.virtualenvs/myproject

again, sphinx tells me that "docs/source/modules.rst already exists, skipping" which of course is true as I have already run sphinx-apidoc once to generate it.

So how do I execute it once and search in both directories?

Answer 1

According to the Sphinx apidoc documentation, the commandline syntax is:

sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames ...]

Update: wrong, see comment by @jgbarah below.

This means that if you want to document sources in two separate directories, you can pass both directories/pathnames at once, so something like:

sphinx-apidoc -o docs/source ~/work/myproject ~/.virtualenvs/myproject

Improved suggestion:

You could make a subdirectory inside your documentation per project. So something like:

sphinx-apidoc -o docs/source/app1 ~/work/myproject1
sphinx-apidoc -o docs/source/app2 ~/work/myproject2

With a toctree you could then point at the two subdirectories:

.. toctree::
    :maxdepth: 2

    app1/index.rst
    app2/index.rst