Re: [PATCH v3 00/33] Convert qemu-doc to rST

[Peter Maydell]

Hi Stefan -- I meant to cc you on these but forgot, relating to the
"qemu.nsi needs updating to know that it should install
Sphinx documentation these days" part...

On Fri, 28 Feb 2020 at 15:36, Peter Maydell <address@hidden> wrote:
>
> Hi; this series does a complete conversion of qemu-doc from
> Texinfo to rST, including the hxtool-generated parts and
> creation of the qemu.1 manpage from rST.
>
> It's marked v3 because it's a development of the v2 that
> Paolo sent out earlier this week.
>
> Changes from v2:
>  * I made the various review-comment fixes I suggested in
>    replies to Paolo's series
>  * rebased on current master
>  * new patches at the end of the series which do the conversion
>    of the .hx file doc fragments to rST
>    (I did part of this semi-by-hand and then qemu-options.hx
>    entirely automatically)
>  * new patches which generate the qemu.1 manpage with Sphinx
>  * new patches which remove the old qemu-doc makefile runes
>    and other references to it
>  * new patches which delete the old texinfo sources, etc
>
> The only thing left still using Texinfo after this is the
> docs autogenerated from the QAPI doc-comments, which are
> their own standalone html and manpages so not affected by this.
>
> A couple of notes:
>  * I haven't actually been in a position to test the cocoa.m
>    update of the HTML filename
>  * qemu.nsi (the Windows installer config file) thinks that
>    qemu-doc.html is the only doc file it needs to know about,
>    which is clearly wrong. However I don't have any idea about
>    the Windows installer to be able to update or test it...
>
> The conversion is a little rough around the edges in a few
> place (mostly I have noted in commit messages when this is
> the case) but I would like to argue for (assuming we're happy
> with the series broadly) taking it into master and then refining
> it in-place. Having it out-of-tree for long is an invitation
> to conflicts and to accidentally losing docs updates if they
> hit master as changes to the texi or hx files before this
> series goes in.
>
> You can find a prerendered set of docs at
> https://people.linaro.org/~peter.maydell/qdoc-no-texi/
> (the interesting part is the system emulation user's guide,
> mostly), and a copy of the new manpage at
> https://people.linaro.org/~peter.maydell/qemu.1
> (download and examine with 'man -l path/to/qemu.1').
>
> thanks
> -- PMM