Re: [PATCH 01/18] qemu-doc: convert user-mode emulation to a separate Sphinx manual

[Peter Maydell <peter.maydell@linaro.org>]

On Wed, 26 Feb 2020 at 11:30, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> The final addition to the set of QEMU manuals is the user-mode emulation
> manual, which right now is included in qemu-doc.texi.  Extract it and
> convert it to rST, so that qemu-doc.texi covers only full system emulation.
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

I'm going to wade in and start making review comments, but
I'm happy to just take on this series and clean it up myself
for a v2 (I'd like to quickly get to a base where I can start
on dealing with the last bits of qemu-doc conversion that
deal with hxtool.)

Did you do the conversion to rST automatically? If so then
it would be useful to give the runes used in the commit message.

> ---
>  Makefile            |   8 +-
>  docs/user/conf.py   |  18 +++
>  docs/user/index.rst |  16 +++
>  docs/user/main.rst  | 295 ++++++++++++++++++++++++++++++++++++++
>  qemu-doc.texi       | 337 --------------------------------------------
>  5 files changed, 336 insertions(+), 338 deletions(-)
>  create mode 100644 docs/user/conf.py
>  create mode 100644 docs/user/index.rst
>  create mode 100644 docs/user/main.rst

A new manual also needs to be added to docs/index.html.in
and to docs/index.rst.

(Compare 0928523a1230a69 which added the system manual.)

>
> diff --git a/Makefile b/Makefile
> index 15f8e53d05..73d8ed2b6a 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -786,6 +786,7 @@ distclean: clean
>         $(call clean-manual,interop)
>         $(call clean-manual,specs)
>         $(call clean-manual,system)
> +       $(call clean-manual,user)

This doesn't apply to current master because of the addition
of the 'tools' manual, but the fixes to the conflicts are easy.

>         for d in $(TARGET_DIRS); do \
>         rm -rf $$d || exit 1 ; \
>          done
> @@ -843,6 +844,7 @@ install-sphinxdocs: sphinxdocs
>         $(call install-manual,interop)
>         $(call install-manual,specs)
>         $(call install-manual,system)
> +       $(call install-manual,user)
>
>  install-doc: $(DOCS) install-sphinxdocs
>         $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
> @@ -1036,7 +1038,8 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
>  sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
>              $(MANUAL_BUILDDIR)/interop/index.html \
>              $(MANUAL_BUILDDIR)/specs/index.html \
> -            $(MANUAL_BUILDDIR)/system/index.html
> +            $(MANUAL_BUILDDIR)/system/index.html \
> +            $(MANUAL_BUILDDIR)/user/index.html
>
>  # Canned command to build a single manual
>  # Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
> @@ -1069,6 +1072,9 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
>  $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
>         $(call build-manual,system,html)
>
> +$(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user)
> +       $(call build-manual,user,html)
> +
>  $(call define-manpage-rule,interop,\
>         qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
>         virtiofsd.1 virtfs-proxy-helper.1,\
> diff --git a/docs/user/conf.py b/docs/user/conf.py
> new file mode 100644
> index 0000000000..b3e1b2318a
> --- /dev/null
> +++ b/docs/user/conf.py
> @@ -0,0 +1,18 @@
> +# -*- coding: utf-8 -*-
> +#
> +# QEMU documentation build configuration file for the 'system' manual.

Should say 'user'.

> +#
> +# This includes the top level conf file and then makes any necessary tweaks.
> +import sys
> +import os
> +
> +qemu_docdir = os.path.abspath("..")
> +parent_config = os.path.join(qemu_docdir, "conf.py")
> +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
> +
> +# This slightly misuses the 'description', but is the best way to get
> +# the manual title to appear in the sidebar.
> +html_theme_options['description'] = u'User Mode Emulation User''s Guide'
> +# One entry per manual page. List of tuples
> +# (source start file, name, description, authors, manual section).
> +man_pages = []

You can just not specify man_pages at all if the manual
doesn't create any manpages (devel and specs are like this):
docs/conf.py sets it to [] by default.

> diff --git a/docs/user/index.rst b/docs/user/index.rst
> new file mode 100644
> index 0000000000..c81d2898cd
> --- /dev/null
> +++ b/docs/user/index.rst
> @@ -0,0 +1,16 @@
> +.. This is the top level page for the 'system' manual.

Should say 'user'.

> +
> +
> +QEMU User Mode Emulation User's Guide
> +=====================================
> +
> +This manual is the overall guide for users using QEMU
> +for user-mode emulation.  In this mode, QEMU can launch
> +processes compiled for one CPU on another CPU.
> +
> +Contents:
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   main

The top level document looks a bit odd with this toctree
which has a single level 1 entry whose title is basically
the same as the whole manual's title, but it gives us a
structure we can expand later I guess.

thanks
-- PMM