Re: [PATCH 09/57] docs/qapi-domain: add QAPI xref roles

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Add domain-specific cross-reference syntax. As of this commit, that
> means new :qapi:mod:`block-core` and :qapi:any:`block-core` referencing
> syntax.
>
> :mod: will only find modules, but :any: will find anything registered to
> the QAPI domain. (In forthcoming commits, this means commands, events,
> enums, etc.)

I understand :any: will find any QAPI schema definitions.  Does it find
modules, too?

How could roles narrower than "definition" be useful?

I'm asking because naming rules preclude naming collisions among
definitions:

* Events are ALL_CAPS

* Commands are lower-case-with-dashes, except some older ones use
  underscores (pragma command-name-exceptions).

* Types are CamelCase.  Note that "C" is not considered a camel.

Fine print: these are the rules for stems, i.e. the name without RFQDN
or 'x-' prefixes, if any.

If :any: finds modules, then commands and modules could collide.
Nothing else can.

> Creating the cross-references is powered by the QAPIXRefRole class;
> resolving them is handled by QAPIDomain.resolve_xref().
>
> QAPIXrefRole is copied almost verbatim from Sphinx's own
> PyXrefRole. PyXrefRole (and QAPIXrefRole) adds two features over the
> base class:
>
> (1) Creating a cross-reference with e.g. :py:class:`~class.name`
> instructs sphinx to omit the fully qualified parts of the resolved name
> from the actual link text. This may be useful in the future if we add
> namespaces to QAPI documentation, e.g. :qapi:cmd:`~qsd.blockdev-backup`
> could link to the QSD-specific documentation for blockdev-backup while
> omitting that prefix from the link text.
>
> (2) Prefixing the link target with a "." changes the search behavior to
> prefer locally-scoped items first.
>
> I think both of these are worth keeping to help manage future namespace
> issues between QEMU, QSD and QGA; but it's possible it's extraneous. It
> may possibly be worth keeping just to keep feature parity with Sphinx's
> other domains; e.g. "principle of least surprise". Dunno.

I generally avoid features without uses.  But I trust your judgement
here: you decide.

> Signed-off-by: John Snow <jsnow@redhat.com>