Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want

[Cleber Rosa]

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.