Re: [PATCH v6 00/21] Convert QAPI doc comments to generate rST instead of texinfo

[John Snow]

On 9/25/20 1:02 PM, Peter Maydell wrote:
> On Fri, 25 Sep 2020 at 17:54, John Snow <jsnow@redhat.com> wrote:
> > On 9/25/20 12:22 PM, Peter Maydell wrote:
> > >    * although there are HTML anchors on all the command/object/etc
> > >      headings, they are not stable but just serial-number based
> > >      tags like '#qapidoc-35', so not suitable for trying to link
> > >      to from other parts of the docs
> >
> > I suppose this answers my question if qmp commands were going to be able
> > to be cross-referenced yet.
> >
> > I'd love to get that working so I can make smart references in the
> > bitmaps doc.
> >
> > We could even amend the QMP code parser to insert cross-references to
> > the function names, which would be *extremely* slick.
>
> If you'd like to have a closer look into Sphinx's indexing
> support, be my guest :-)
Yeah, I am *absolutely* not suggesting this for this series.

I did start taking a look at Sphinx's default_role. As an exercise for 
the Python cleanup, I looked at what would happen if I set our default 
role to "Any" to be able to cross-reference using `backticks`.

I used this to test my docstring consistency for the QAPI module 
cleanup. It involved me converting a few usages of single backticks in 
./docs proper to double-backticks, but it wasn't too bad.

(See the "DO-NOT-MERGE" commits on my part1 V3.)

I'll look into how we *add* reference targets; that part I still have no 
clue on. but adding a qmp reference scope would be *delightful*.

> -- PMM