Re: [PATCH] build: Build and install the info manual.

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

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