Re: Proposal for handling .hx files with Sphinx

[Peter Maydell]

On Tue, 21 Jan 2020 at 11:12, Peter Maydell <address@hidden> wrote:
>
> On Tue, 21 Jan 2020 at 06:40, Markus Armbruster <address@hidden> wrote:
> > John Snow <address@hidden> 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.

thanks
-- PMM