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

[Paolo Bonzini]

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
>