Re: [PATCH 14/18] docs/system: Convert qemu-cpu-models.texi to rST

[Peter Maydell]

On Wed, 26 Feb 2020 at 11:30, Paolo Bonzini <address@hidden> wrote:
>
> From: Kashyap Chamarthy <address@hidden>
>
> This doc was originally written by Daniel P. Berrangé
> <address@hidden>, introduced via commit[1]: 2544e9e4aa (docs: add
> guidance on configuring CPU models for x86, 2018-06-27).
>
> In this patch:
>
>   - 1-1 conversion of Texinfo to rST, besides a couple of minor
>     tweaks that are too trivial to mention.   (Thanks to Stephen
>     Finucane on IRC for the suggestion to use rST "definition lists"
>     instead of bullets in some places.)
>
>     Further modifications will be done via a separate patch.
>
>   - rST and related infra changes: manual page generation, Makefile
>     fixes, clean up references to qemu-cpu-models.texi, update year in
>     the copyright notice, etc.
>
> [1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa

> Signed-off-by: Kashyap Chamarthy <address@hidden>
> [Move macros to defs.rst.inc, split in x86 and MIPS parts,
>  make qemu-cpu-models.rst a standalone document. - Paolo]
> Signed-off-by: Paolo Bonzini <address@hidden>
> ---
>  MAINTAINERS                         |   2 +-
>  Makefile                            |   3 +-
>  docs/conf.py                        |   2 +-
>  docs/system/conf.py                 |  10 +-
>  docs/system/cpu-models-mips.rst.inc | 105 ++++++++
>  docs/system/cpu-models-x86.rst.inc  | 365 ++++++++++++++++++++++++++++
>  docs/system/defs.rst.inc            |   2 +
>  docs/system/qemu-block-drivers.rst  |   2 -
>  docs/system/qemu-cpu-models.rst     |  20 ++
>  docs/system/qemu-cpu-models.texi    |  28 ---
>  10 files changed, 504 insertions(+), 35 deletions(-)
>  create mode 100644 docs/system/cpu-models-mips.rst.inc
>  create mode 100644 docs/system/cpu-models-x86.rst.inc
>  create mode 100644 docs/system/defs.rst.inc
>  create mode 100644 docs/system/qemu-cpu-models.rst
>  delete mode 100644 docs/system/qemu-cpu-models.texi

Why don't we also delete cpu-models-x86.texi and
cpu-models-mips.texi ?

> diff --git a/MAINTAINERS b/MAINTAINERS
> index 0d3ee8bdc6..01d1ee4b50 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -320,7 +320,7 @@ F: tests/tcg/i386/
>  F: tests/tcg/x86_64/
>  F: hw/i386/
>  F: disas/i386.c
> -F: docs/system/cpu-models-x86.texi
> +F: docs/system/cpu-models-x86.rst

This isn't the filename the patch actually uses.

There should be a corresponding new F: line for the mips version too.

>  T: git https://github.com/ehabkost/qemu.git x86-next
>
>  Xtensa TCG CPUs
> diff --git a/Makefile b/Makefile
> index 6b5193b838..a79f751d5d 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1080,7 +1080,7 @@ $(call define-manpage-rule,interop,\
>         virtiofsd.1 virtfs-proxy-helper.1,\
>         $(SRC_PATH)/qemu-img-cmds.hx)
>
> -$(call define-manpage-rule,system,qemu-block-drivers.7)
> +$(call define-manpage-rule,system,qemu-block-drivers.7 qemu-cpu-models.7)
>
>  $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
>         @mkdir -p "$(MANUAL_BUILDDIR)"
> @@ -1104,7 +1104,6 @@ docs/interop/qemu-ga-qapi.texi: 
> qga/qapi-generated/qga-qapi-doc.texi
>
>  qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi 
> qemu-monitor-info.texi
>  qemu.1: docs/system/qemu-option-trace.texi
> -docs/system/qemu-cpu-models.7: docs/system/qemu-cpu-models.texi 
> docs/system/cpu-models-x86.texi docs/system/cpu-models-mips.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

The install line for qemu-cpu-models.7 also needs updating to
include $(MANUAL_BUILDDIR).

The distclean line that removes qemu-cpu-models.7 can be removed.

> diff --git a/docs/conf.py b/docs/conf.py
> index 7588bf192e..1650fc8698 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -80,7 +80,7 @@ master_doc = 'index'
>
>  # General information about the project.
>  project = u'QEMU'
> -copyright = u'2019, The QEMU Project Developers'
> +copyright = u'2020, The QEMU Project Developers'
>  author = u'The QEMU Project Developers'
>
>  # The version info for the project you're documenting, acts as replacement 
> for

We should indeed fix the copyright date, but not in the middle
of this texi->rst series, and we should update the QEMU_COPYRIGHT
macro in qemu-common.h at the same time.

> diff --git a/docs/system/conf.py b/docs/system/conf.py
> index 7ca115f5e0..8d41f4da43 100644
> --- a/docs/system/conf.py
> +++ b/docs/system/conf.py
> @@ -13,10 +13,18 @@ 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'System Emulation User''s Guide'
> +
> +rst_prolog = '''
> +.. include:: defs.rst.inc
> +'''
> +

Maybe we should do this in docs/conf.py where we update
rst_epilog with the CONFDIR replacement ?

Doing the "put these replacements into a generic defs.rst.inc"
would also be clearer in its own patch, I think.

>  # One entry per manual page. List of tuples
>  # (source start file, name, description, authors, manual section).
>  man_pages = [
>      ('qemu-block-drivers', 'qemu-block-drivers',
>       u'QEMU block drivers reference',
> -     ['Fabrice Bellard and the QEMU Project developers'], 7)
> +     ['Fabrice Bellard and the QEMU Project Developers'], 7),

If we want to capitalize the 'D' in Developers, we should
make that fix in its own commit, and we should update
the QEMU_COPYRIGHT macro too, for consistency.

> +    ('qemu-cpu-models', 'qemu-cpu-models',
> +     u'QEMU CPU Models',
> +     ['The QEMU Project Developers'], 7)
>  ]

I would mention explicitly in the commit message that Dan agreed
to the updating of the manpage's Author information to
the more generic string.

thanks
-- PMM