On Tue, Mar 05, 2019 at 05:21:35PM +0000, Peter Maydell wrote: > By default Sphinx wants to build a single manual at once. > For QEMU, this doesn't suit us, because we want to have > separate manuals for "Developer's Guide", "User Manual", > and so on, and we don't want to ship the Developer's Guide > to end-users. However, we don't want to completely duplicate > conf.py for each manual, and we'd like to continue to > support "build all docs in one run" for third-party sites > like readthedocs.org. > > Make the top-level conf.py support two usage forms: > (1) as a common config file which is included by the conf.py > for each of QEMU's manuals: in this case sphinx-build is run > multiple times, once per subdirectory. > (2) as a top level conf file which will result in building all > the manuals into a single document: in this case sphinx-build is > run once, on the top-level docs directory. > > Provide per-manual conf.py files and top level pages for > our first two manuals: > * QEMU Developer's Guide (docs/devel) > * QEMU System Emulation Management and Interoperability Guide > (docs/interop) >
I have the impression that this can be simplified by making use of "only" tags: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only So, conf.py could detect if it's being run on readthedocs.org: ON_RTD = os.environ.get('READTHEDOCS', None) == 'True' And manipulate the "tags" variable accordingly: if ON_RTD: tags.add('devel') tags.add('interop') Then, on an index.rst, it could be a simple matter of: .. only:: devel ================ Developers Guide ================ .. toctree:: docs/devel .. only:: interop ============= Interop Guide ============= .. toctree:: docs/interop .. only:: devel and interop =============== QEMU Full Guide =============== .. toctree:: docs/devel docs/interop Or some alternative layout. Please beware that I haven't performed a full examination of that (or similar) approach. If that doesn't work, I'd consider having a top level "common.py", whose contents are imported by the various "conf.py", instead of exec()'d. That I've tried, and a simple: from common import * release = 'overridden_value' Works as expected and is respected by sphinx. - Cleber.
