[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: |
Paolo Bonzini |
Subject: |
Re: [PATCH 01/18] qemu-doc: convert user-mode emulation to a separate Sphinx manual |
Date: |
Thu, 27 Feb 2020 14:08:30 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 |
On 27/02/20 12:07, Peter Maydell wrote:
> 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.
I started from the pandoc conversion but, unlike the others, this one
was reviewed, so I didn't include the command line.
Paolo
>> ---
>> 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 07/18] qemu-doc: move system requirements chapter inside PC section, (continued)
- [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
- [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
- [PATCH 14/18] docs/system: Convert qemu-cpu-models.texi to rST, Paolo Bonzini, 2020/02/26