[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] build: Build and install the info manual.
From: |
Maxim Cournoyer |
Subject: |
Re: [PATCH] build: Build and install the info manual. |
Date: |
Sat, 26 Sep 2020 22:22:33 -0400 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
Hello Peter,
Peter Maydell <peter.maydell@linaro.org> writes:
> On Sat, 26 Sep 2020 at 05:36, Maxim Cournoyer <maxim.cournoyer@gmail.com>
> wrote:
>> > This isn't the right thing. You should be pointing sphinx-build
>> > at each of the individual manuals (system, interop, etc) and
>> > generating one info file for each. This is because we generate
>> > manuals for each of these including the 'devel' manual, but
>> > we don't want to install 'devel', because it's developer-facing
>> > and not needed by end-users of QEMU.
>>
>> Is this the only reason individual manuals are being generated? It
>> makes sense for the manpages (which have their own macros), but
>> otherwise (for HTML and info) introduces a lot of complexity for not
>> much gain, in my opinion. Users not wanting to know about devel
>> internals can simply skip that section; no harm done.
>
> It is the best way we found for getting Sphinx to do what we wanted.
> I agree that it would be nicer to have one manual with all the user
> facing parts in it, but it is apparently not possible to do that without
> shipping the devel docs to users, which we didn't want to do.
I personally don't understand the rationale of hiding the devel section
from users, especially given the kind of users QEMU is likely to attract
(e.g, teksavvy people, perhaps themselves developers that could be
curious peeking into that section to deepen their understanding of
QEMU's architecture and internals).
But if you feel strongly about it, I'd suggest the following, which
excludes the devel section from being built when calling Sphinx from the
top level:
--8<---------------cut here---------------start------------->8---
7 files changed, 13 insertions(+), 4 deletions(-)
docs/conf.py | 5 ++++-
docs/cpu-hotplug.rst | 2 ++
docs/index.rst | 3 ---
docs/microvm.rst | 2 ++
docs/pr-manager.rst | 2 ++
docs/virtio-net-failover.rst | 2 ++
docs/virtio-pmem.rst | 1 +
modified docs/conf.py
@@ -116,7 +116,10 @@ language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build',
+ 'Thumbs.db',
+ '.DS_Store',
+ 'devel/*']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
modified docs/cpu-hotplug.rst
@@ -1,3 +1,5 @@
+:orphan:
+
===================
Virtual CPU hotplug
===================
modified docs/index.rst
@@ -9,12 +9,9 @@ Welcome to QEMU's documentation!
.. toctree::
:maxdepth: 2
:caption: Contents:
- :glob:
system/index
user/index
tools/index
interop/index
specs/index
- devel/index
- *
modified docs/microvm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
====================
microvm Machine Type
====================
modified docs/pr-manager.rst
@@ -1,3 +1,5 @@
+:orphan:
+
======================================
Persistent reservation managers
======================================
modified docs/virtio-net-failover.rst
@@ -1,3 +1,5 @@
+:orphan:
+
======================================
QEMU virtio-net standby (net_failover)
======================================
modified docs/virtio-pmem.rst
@@ -1,3 +1,4 @@
+:orphan:
========================
QEMU virtio pmem
--8<---------------cut here---------------end--------------->8---
With this change, the top level node of "info qemu" reads as:
--8<---------------cut here---------------start------------->8---
QEMU Documentation
******************
QEMU , Sep 26, 2020
The QEMU Project Developers
Copyright (C) 2020, The QEMU Project Developers
* Menu:
* QEMU System Emulation User's Guide::
* QEMU User Mode Emulation User's Guide::
* QEMU Tools Guide::
* QEMU System Emulation Management and Interoperability Guide::
* QEMU System Emulation Guest Hardware Specifications::
* Index::
--8<---------------cut here---------------end--------------->8---
I'd still prefer to include the developer's manual as the last section
of the info manual, if you don't mind, for the reason explained above.
The scheme used above to exclude the devel section could also be used to
simplify building the HTML manual (e.g., build it by calling sphinx on
the top level with a correctly defined index.rst instead of individually
for each of its constituting sections before stitching them back
together with a custom index.html).
What do you think?
Thanks again,
Maxim