Re: [PATCH v2 1/2] docs: Convert qemu-cpu-models.texi to rST

[Peter Maydell]

On Wed, 19 Feb 2020 at 11:46, Kashyap Chamarthy <address@hidden> wrote:
>
> 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).
>
> This is a 1-1 conversion of Texinfo to rST, besides a couple of minor
> non-content tweaks that are too trivial to spell out.  Further
> modifications will be done via a separate patch.
>
> (Thanks to Stephen Finucane on IRC for the suggestion to use rST
> "definition lists" instead of bullets in some places.)
>
> [1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa
>
> Signed-off-by: Kashyap Chamarthy <address@hidden>
> ---
>  docs/qemu-cpu-models.texi       | 677 --------------------------------
>  docs/system/index.rst           |   1 +
>  docs/system/qemu-cpu-models.rst | 496 +++++++++++++++++++++++
>  3 files changed, 497 insertions(+), 677 deletions(-)
>  delete mode 100644 docs/qemu-cpu-models.texi
>  create mode 100644 docs/system/qemu-cpu-models.rst

Hi; I haven't looked in detail at the actual conversion
parts, but from the diffstat you're missing some parts:

1) qemu-doc.texi has an "@include docs/qemu-cpu-models.texi"
that needs to be removed. That then means that the
"CPU models" section in qemu-doc.texi is empty, so we
can just delete it (the @node and @section directives,
and the reference to it in the earlier @menu)
(I'm surprised this didn't cause 'make' to fail with
an error trying to build the texi docs.)

2) The bit of Makefile which lists the dependencies of
qemu-doc.html needs to be updated to remove
docs/qemu-cpu-models.texi.

3) we create a qemu-cpu-models.7 manpage, so the parts
of Makefile that currently handle creating it from the
texi need to be changed to do it from the rST instead.
You can look at how we handle qemu-block-drivers.7
for an example. Don't forget that you'll need to add
a line to docs/system/conf.py to get Sphinx to build
the manpage, as well as the makefile changes.
You can check how the manpage renders with
'man -l /path/to/builddir/docs/interop/qemu-cpu-models.7'

4) The qemu-cpu-models.texi uses a substitution
"@set qemu_system_x86 qemu-system-x86-64" so that
downstream RedHat can easily update the examples text
to refer to whatever they rename the binary to. The
equivalent of this in rST you can see in qemu-block-drivers.rst:
at the top of the file we have

.. |qemu_system| replace:: qemu-system-x86_64

and then an example block using it is like:

.. parsed-literal::

  |qemu_system| linux.img -hdb fat:/my_directory

(you have to use a parsed-literal block and not the
usual :: so that the expansion is done.)

thanks
-- PMM