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

[Kashyap Chamarthy <kchamart@redhat.com>]

On Wed, Feb 19, 2020 at 01:16:11PM +0000, Peter Maydell wrote:
> On Wed, 19 Feb 2020 at 11:46, Kashyap Chamarthy <kchamart@redhat.com> wrote:

[...]

> >  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:

Hi, Peter.

Thanks for the helpfully detailed response.  I realized some of the
missing bits due to the Patchew failure and as I look closer into your
patch for qemu-block-drivers.rst.

> 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.)

Ah, noted.  I used the regular :: out of habit from elsewhere, and
didn't even look at the details of qemu-block-drivers.rst.

I'm addressing them as we speak; v2 upcoming.

Thanks, again.

-- 
/kashyap