John Snow <js...@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 <js...@redhat.com>
