Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Peter Maydell <peter.maydell@linaro.org>]

On Tue, 25 Feb 2020 at 20:10, Paolo Bonzini <pbonzini@redhat.com> wrote:
> The main issue with this series and Kashyap's is that if we don't manage to get
> everything done in 5.0 we have a mutilated qemu-doc. Then either we keep it
> mutilated or we scramble to undo the work. So I would agree to commit the
> series in this order, but without the removal of the .texi files.

Kashyap's set is in the same ballpark as what we've currently
converted (notably it's pretty much equivalent to the qemu-block-drivers
conversion in that it takes what was part of qemu-doc plus a manpage
and turns it into part of the system manual plus a manpage).
It's also the most awkward to try to keep the texi around for, because
the makefile runes for the texi want to generate the manpage too.
So I think I would argue for taking that as-is, including removal of the
texi files.

I agree that it would be good to avoid a half-converted qemu-doc;
if people think keeping two parallel doc files until we're sure we
can do the conversion is useful insurance I'm happy to go along
with that.

If we ended up with "we managed all the conversion except for
the qapi json doc comments parts" would we be ok with having a
qemu-doc.html that just contained those, and all the actual docs
transitioning to rST for this release? Or would we want to roll
back the rST for the main qemu-doc parts too in that situation?

thanks
-- PMM