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:

1. 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?

2. 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.

3. 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.

Answer 1

1. I'm not sure what you mean by this. Your project's index appears to be just fine. Could you clarify on this, please?
2. As far as I've seen, from common_config import * is the best approach for keeping configuration in sync.

3. 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!

Answer 2

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