Re: [Qemu-devel] Sketch of a transition of QEMU docs to Sphinx

[John Snow <jsnow@redhat.com>]

On 6/11/19 3:29 AM, Markus Armbruster wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> 
>> On Tue, 21 May 2019 at 19:56, Peter Maydell <peter.maydell@linaro.org> wrote:
>>>
>>> Currently we have a vague plan that we should migrate our
>>> documentation away from Texinfo to using Sphinx, plus some isolated
>>> bits of documentation already in .rst format. This email is an attempt
>>> to sketch out a transition plan for getting us from where we are today
>>> to where (I think) we want to be.
>>
>> Since nobody seemed to disagree particularly with this sketch,
> 
> I don't think rST is an improvement over Texinfo.  As Paolo said, it's
> the Perl of ASCII-based markups.  But I (reluctantly) agree with Paolo
> that our current mix of Texinfo, rST, Markdown, and ad hoc markup is
> worse than consistent use of one markup system, even if it's an
> ill-conceived one like rST.
> 
> March of progress, I guess.
> 
> [...]
> 

I will say that at a minimum I enjoy the combination of sphinx and rST
because at least we can error out on warnings and check that the cross
references are valid.

Markdown is a hot mess of a non-spec that is subtly different for just
about every implementation, and we procedurally check none of ours.

At least rST is one thing, I guess. And that it's extensible via sphinx
is nice.

--js