[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] Sketch of a transition of QEMU docs to Sphinx
From: |
John Snow |
Subject: |
Re: [Qemu-devel] Sketch of a transition of QEMU docs to Sphinx |
Date: |
Tue, 11 Jun 2019 13:36:21 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 |
On 6/11/19 3:29 AM, Markus Armbruster wrote:
> Peter Maydell <address@hidden> writes:
>
>> On Tue, 21 May 2019 at 19:56, Peter Maydell <address@hidden> 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