Re: [PATCH v3 29/33] docs: Generate qemu.1 manpage with Sphinx

["Alex Bennée" <alex.bennee@linaro.org>]

Peter Maydell <peter.maydell@linaro.org> writes:

> Generate the qemu.1 manpage using Sphinx; we do this with a new
> top-level rst source file which is just the skeleton of the manpage
> and which includes .rst.inc fragments where it needs to incorporate
> sections from the larger HTML manuals.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

> ---
>  Makefile                     | 10 ++++----
>  docs/system/conf.py          |  2 ++
>  docs/system/qemu-manpage.rst | 45 ++++++++++++++++++++++++++++++++++++
>  3 files changed, 51 insertions(+), 6 deletions(-)
>  create mode 100644 docs/system/qemu-manpage.rst
>
> diff --git a/Makefile b/Makefile
> index f7d08997dbf..ef10b9a031d 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -344,7 +344,8 @@ MANUAL_BUILDDIR := docs
>  endif
>  
>  ifdef BUILD_DOCS
> -DOCS=qemu-doc.html qemu-doc.txt qemu.1
> +DOCS=qemu-doc.html qemu-doc.txt
> +DOCS+=$(MANUAL_BUILDDIR)/system/qemu.1
>  DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
>  DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
>  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
> @@ -856,7 +857,7 @@ install-doc: $(DOCS) install-sphinxdocs
>  	$(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
>  ifdef CONFIG_POSIX
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
> -	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu.1 "$(DESTDIR)$(mandir)/man1"
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
>  	$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
>  	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
> @@ -1082,7 +1083,7 @@ $(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user)
>  
>  $(call define-manpage-rule,interop,qemu-ga.8)
>  
> -$(call define-manpage-rule,system,qemu-block-drivers.7 qemu-cpu-models.7)
> +$(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-models.7)
>  
>  $(call define-manpage-rule,tools,\
>         qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
> @@ -1109,9 +1110,6 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
>  docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
>  	@cp -p $< $@
>  
> -qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
> -qemu.1: docs/system/qemu-option-trace.texi
> -
>  html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
>  info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
>  pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
> diff --git a/docs/system/conf.py b/docs/system/conf.py
> index 23cab3fb364..6251849fefc 100644
> --- a/docs/system/conf.py
> +++ b/docs/system/conf.py
> @@ -17,6 +17,8 @@ html_theme_options['description'] = u'System Emulation User''s Guide'
>  # One entry per manual page. List of tuples
>  # (source start file, name, description, authors, manual section).
>  man_pages = [
> +    ('qemu-manpage', 'qemu', u'QEMU User Documentation',
> +     ['Fabrice Bellard'], 1),
>      ('qemu-block-drivers', 'qemu-block-drivers',
>       u'QEMU block drivers reference',
>       ['Fabrice Bellard and the QEMU Project developers'], 7),
> diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
> new file mode 100644
> index 00000000000..e9a25d0680f
> --- /dev/null
> +++ b/docs/system/qemu-manpage.rst
> @@ -0,0 +1,45 @@
> +:orphan:
> +
> +..
> +   This file is the skeleton for the qemu.1 manpage. It mostly
> +   should simply include the .rst.inc files corresponding to the
> +   parts of the documentation that go in the manpage as well as the
> +   HTML manual.
> +
> +Title
> +=====
> +
> +Synopsis
> +--------
> +
> +.. parsed-literal::
> +
> +   |qemu_system| [options] [disk_image]
> +
> +Description
> +-----------
> +
> +.. include:: target-i386-desc.rst.inc
> +
> +Options
> +-------
> +
> +disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
> +not need a disk image.
> +
> +.. hxtool-doc:: qemu-options.hx
> +
> +.. include:: keys.rst.inc
> +
> +.. include:: mux-chardev.rst.inc
> +
> +Notes
> +-----
> +
> +.. include:: device-url-syntax.rst.inc
> +
> +See also
> +--------
> +
> +The HTML documentation of QEMU for more precise information and Linux
> +user mode emulator invocation.


-- 
Alex Bennée