Re: Proposal for handling .hx files with Sphinx

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Tue, 21 Jan 2020 at 11:12, Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> On Tue, 21 Jan 2020 at 06:40, Markus Armbruster <armbru@redhat.com> wrote:
>> > John Snow <jsnow@redhat.com> writes:
>> > > Still, I do want to ask: Are we sure we want to double-down on keeping
>> > > the .hx files around instead of trying to move to a more generic data
>> > > format?
>> >
>> > One the one hand, I'd prefer to invest as little as practical into .hx.
>> > On the other hand, adding more hard dependencies on QAPIfication is not
>> > a good idea.
>> >
>> > What's the stupidest solution that could possibly work now?  Is it the
>> > one Peter sketched?
>>
>> FWIW, I wrote some code for the Sphinx extension approach yesterday,
>> along the 'simplest possible thing' lines. It's less than 200 lines
>> of Python (though I still need to put in the support for DEFHEADING
>> and ARCHHEADING). The actual texinfo fragments in the various .hx
>> files of course would also need to be hand-converted to rST, same
>> as the hand-written manual .texi file contents.
>
> Incidentally, I am definitely coming to the conclusion that the
> best way to do generation of docs to go in Sphinx manuals is
> to use/write a Sphinx extension -- this lets you properly create
> doctree nodes, for instance and it fits the flow better. So a
> in potential future where we were generating these docs from
> json, I think we'd want to have a Sphinx extension driving the
> 'parse the json for docs', rather than a separate script that
> spit out rst-format-text to include.

I trust your judgement.

Since the Sphinx extension is in Python, we can try to reuse the QAPI
frontend there.  We'll see.

I'd like to encourage you to not feel bound to the existing doc comment
language.  When Marc-André created the doc generator, he chose to fit
the doc comment language to the existing doc comments, to avoid churn.
That was probably the right decision then; getting the job done was
tough enough as it was.  The resulting language was basically defined by
its (ad hoc!) parser.  I cleaned up the parser some, and
retro-documented the syntax.  It's still an idiosyncratic mess, to be
honest.