Combining Sphinx documentation from multiple subprojects: Handling indices, syncing configuration, etc

Question

We have a multi-module project documented with the (excellent) Sphinx. Our setup is not unlike one described on the mailing list. Overall this works great! But we have a few questions about doing so:

The submodule tables of contents will include index links. At best these will link to the wrong indices. (At worst this seems to trigger a bug in Sphinx, but I'm using the devel version so that's reasonable). Is there a way of generating the index links only for the topmost toctree?
Are there best practices for keeping the Sphinx configuration in sync between multiple projects? I could imagine hacking something together around from common_config import *, but curious about other approaches.
While we're at it, the question raised in the mailing list post (alternative to symlinking subproject docs?) was never answered. It's not important to me, but it may be important to other readers.

The http://csc.media.mit.edu/docs URL does not work. – mzjn Jan 31 '17 at 06:39 — mzjn, Jan 31 '17 at 06:39

DangerOnTheRanger · Accepted Answer · 2011-06-26T14:16:20.393

I'm not sure what you mean by this. Your project's index appears to be just fine. Could you clarify on this, please?
As far as I've seen, from common_config import * is the best approach for keeping configuration in sync.
I think the best way to do this is something like the following directory structure:
```
main-project/
 conf.py
 documentation.rst

 sub-project-1/
    conf.py - imports from main-project/conf.py
    documentation.rst

 sub-project-2/
    conf.py - likewise, imports from main-project/conf.py
    documentation.rst
```
Then, to just package sub-project-1 or sub-project-2, use this UNIX command:
```
sphinx-build main-project/ <output directory> <paths to sub-project docs you want to add>
```
That way, not only will the main project's documentation get built, the sub-project documentation you want to add will be added as well.

To package main-project:
```
sphinx-build main-project/ <output directory>
```
I'm pretty sure this scheme will work, but I've yet to test it out myself.

Hope this helps!

score 0 · Answer 2 · edited Aug 23 '19 at 00:07

Regarding point 2 (including common configuration), I'm using:

In Python 2:

execfile (os.path.abspath("../../common/conf.py"))

In Python 3:

exec (open('../../common/conf.py').read())

Note that, unlike the directory structure presented by @DangerOnTheRanger, I prefer to keep a separate directory for common documentation, which is why common appears in the path above.

My common/conf.py file is a normal Sphynx file. Then, each of the specific documentation configuration includes that common file and overrides values as necessary, like in this example:

import sys
import os

execfile (os.path.abspath("../../common/conf.py"))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
]

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

# If true, links to the reST sources are added to the pages.
html_copy_source = False
html_show_sourcelink = False

Very interesting. Could you explain how you build the docs? Do you have a single `_build`? Do you run `sphinx-build` for every sub-project? — Daniel Node.js, Dec 31 '18 at 20:11
@DanielPendergast yes. I have a main Makefile that calls the two Makefiles in each of the doc subprojects. But in the end, yes, you have to call them separately with this approach. I keep two separate output directories (I don't use _build, as we build everything to a different target directory). We build two separate sets of html and pdf files (for separate audiences). — jjmontes, Jan 01 '19 at 00:30

Combining Sphinx documentation from multiple subprojects: Handling indices, syncing configuration, etc

2 Answers2

Linked