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?
Okay, here\’s the best answer to address the issue of using `sphinx-apidoc` with multiple source directories, focusing on clarity, conciseness, and practical solutions:\n\n**Best Answer:**\n\nThe most straightforward and recommended approach to have `sphinx-apidoc` process Python source files from multiple directories is to list all directories as arguments in a single command. `sphinx-apidoc` accepts multiple input paths.\n\nHere\’s how to do it:\n\n“`bash\nsphinx-apidoc -o docs/source ~/work/myproject ~/.virtualenvs/myproject\n“`\n\n**Explanation and Important Considerations:**\n\n* **Single Invocation:** By providing both directories in a single command, `sphinx-apidoc` will analyze all files within those directories and generate the necessary reStructuredText (`.rst`) files in the `docs/source` directory *in one go*. This avoids the \”modules.rst already exists\” problem.\n\n* **Recursive Search:** `sphinx-apidoc` searches the given directories *recursively* by default. So, it will find `.py` files in subdirectories within `~/work/myproject` and `~/.virtualenvs/myproject`.\n\n* **Overwriting:** If you\’ve already run `sphinx-apidoc` and want to regenerate the documentation (perhaps you\’ve added new modules), you might want to use the `-f` (or `–force`) flag to force overwriting of existing `.rst` files:\n\n “`bash\n sphinx-apidoc -f -o docs/source ~/work/myproject ~/.virtualenvs/myproject\n “`\n\n* **Excluding Paths:** You might need to *exclude* certain directories or files from the documentation. Use the `-e` option to put the exclude paths in a file called `exclude.txt` and then call the `sphinx-apidoc` command with the `-e` option.\n\n First, create `exclude.txt` in your root documentation directory (where `conf.py` resides). Add paths *relative to the source directories* you\’re documenting. For instance, if you want to exclude a `tests` directory inside `~/work/myproject`, and a `legacy` directory inside `~/.virtualenvs/myproject`, your `exclude.txt` file might look like this:\n\n “`text\n tests\n legacy\n “`\n\n Then, run:\n\n “`bash\n sphinx-apidoc -o docs/source ~/work/myproject ~/.virtualenvs/myproject -e exclude.txt\n “`\n\n* **`conf.py` integration**: After running `sphinx-apidoc`, remember to update your `conf.py` file (usually located in `docs/source`) to include the generated modules in your `toctree`. Specifically, look for the `toctree` directive in your `index.rst` file and make sure it includes the `modules` file (or whatever name `sphinx-apidoc` generated for your main modules index).\n\n “`rst\n .. toctree::\n :maxdepth: 2\n :caption: Contents:\n\n modules\n “`\n\n* **Path Precedence/Conflicts**: If modules with the same name exist in both directories, the module found first will be used. Be mindful of potential naming conflicts and how this might affect your documentation. Consider renaming or restructuring your modules to avoid confusion.\n\n**Example Scenario:**\n\nLet\’s say you have:\n\n* `~/work/myproject/module_a.py`\n* `~/work/myproject/subdir/module_b.py`\n* `~/.virtualenvs/myproject/module_c.py`\n* `~/.virtualenvs/myproject/legacy/module_d.py` (which you want to exclude)\n\nYou would:\n\n1. Create `exclude.txt` in `docs/source` containing:\n\n “`text\n legacy\n “`\n\n2. Run:\n\n “`bash\n sphinx-apidoc -o docs/source ~/work/myproject ~/.virtualenvs/myproject -e exclude.txt\n “`\n\nThis will generate `.rst` files for `module_a`, `module_b`, and `module_c` in `docs/source`, and exclude `module_d`. Then, make sure `index.rst` has `modules` in the `toctree`.\n\n**Why this is the best answer:**\n\n* **Simplicity:** It provides the most direct and easiest-to-understand solution.\n* **Completeness:** It addresses the core problem and anticipates common follow-up issues like overwriting and excluding files.\n* **Best Practice:** It aligns with the intended usage of `sphinx-apidoc`.\n* **Clarity:** The explanation breaks down each step and provides context for why each option is used.\n* **Practical Example:** The example scenario solidifies understanding and shows how to apply the solution in a real-world situation.\n
