[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: John Snow
Subject: Re: [PATCH v6 00/21] Convert QAPI doc comments to generate rST instead of texinfo
Date: Fri, 25 Sep 2020 13:09:02 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.11.0

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]