[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 01/18] qemu-doc: convert user-mode emulation to a separate Sp
From: |
Peter Maydell |
Subject: |
Re: [PATCH 01/18] qemu-doc: convert user-mode emulation to a separate Sphinx manual |
Date: |
Thu, 27 Feb 2020 11:07:37 +0000 |
On Wed, 26 Feb 2020 at 11:30, Paolo Bonzini <address@hidden> 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 <address@hidden>
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
- [PATCH 02/18] qemu-doc: remove target OS documentation, (continued)
- [PATCH 02/18] qemu-doc: remove target OS documentation, Paolo Bonzini, 2020/02/26
- [PATCH 07/18] qemu-doc: move system requirements chapter inside PC section, Paolo Bonzini, 2020/02/26
- [PATCH 04/18] qemu-doc: split CPU models doc between MIPS and x86 parts, Paolo Bonzini, 2020/02/26
- [PATCH 06/18] qemu-doc: extract common system emulator documentation from the PC section, Paolo Bonzini, 2020/02/26
- [PATCH 11/18] qemu-doc: move included files to docs/system, Paolo Bonzini, 2020/02/26
- [PATCH 01/18] qemu-doc: convert user-mode emulation to a separate Sphinx manual, Paolo Bonzini, 2020/02/26
- Re: [PATCH 01/18] qemu-doc: convert user-mode emulation to a separate Sphinx manual,
Peter Maydell <=
- [PATCH 10/18] qemu-doc: move qemu-tech.texi into main section, Paolo Bonzini, 2020/02/26
- [PATCH 09/18] qemu-doc: Remove the "CPU emulation" part of the "Implementation notes", Paolo Bonzini, 2020/02/26
- [PATCH 12/18] qemu-doc: remove indices other than findex, Paolo Bonzini, 2020/02/26
- [PATCH 16/18] docs/system: convert managed startup to rST., Paolo Bonzini, 2020/02/26
- [PATCH 15/18] docs/system: Convert security.texi to rST format, Paolo Bonzini, 2020/02/26
- [PATCH 08/18] qemu-doc: split target sections to separate files, Paolo Bonzini, 2020/02/26