[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for eac
From: |
Cleber Rosa |
Subject: |
Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want |
Date: |
Wed, 6 Mar 2019 20:40:28 -0500 |
User-agent: |
NeoMutt/20180716 |
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.
- Re: [Qemu-devel] [PATCH v3 03/12] docs: Commit initial files from sphinx-quickstart, (continued)
- [Qemu-devel] [PATCH v3 06/12] docs/conf.py: Don't include rST sources in HTML build, Peter Maydell, 2019/03/05
- [Qemu-devel] [PATCH v3 07/12] docs/conf.py: Disable option warnings, Peter Maydell, 2019/03/05
- [Qemu-devel] [PATCH v3 10/12] Makefile: Abstract out "identify the pkgversion" code, Peter Maydell, 2019/03/05
- [Qemu-devel] [PATCH v3 09/12] Makefile, configure: Support building rST documentation, Peter Maydell, 2019/03/05
- [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Peter Maydell, 2019/03/05
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want,
Cleber Rosa <=
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Peter Maydell, 2019/03/07
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Cleber Rosa, 2019/03/07
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Peter Maydell, 2019/03/07
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Cleber Rosa, 2019/03/07
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Peter Maydell, 2019/03/07
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Cleber Rosa, 2019/03/07
- Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want, Peter Maydell, 2019/03/07
[Qemu-devel] [PATCH v3 11/12] docs/conf.py: Don't hard-code QEMU version, Peter Maydell, 2019/03/05
[Qemu-devel] [PATCH v3 12/12] MAINTAINERS: Add entry for Sphinx documentation infrastructure, Peter Maydell, 2019/03/05