On Fri, Mar 7, 2025 at 5:09 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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? > `block-core` and :any:`block-core` will find modules, yes. So will :qapi:mod:`block-core` and :qapi:any:`block-core`. > > How could roles narrower than "definition" be useful? > At the very least, :qapi:type:`foo` - which omits commands, events, and modules -- is useful for the role to apply to field lists, since those things can never possibly be anything other than a data type. The parser may protect for this, but the QAPI domain also doesn't bother allowing any such mishaps either. > 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. > Right, the narrow roles might not be that useful in practice, but they also cost virtually nothing codewise. I will admit to just copying the Python domain. I almost feel as if they're interesting to leave in if only to serve as documentation for how one could narrow the xref roles, but ... yeah, I admit it's a bit superfluous. > > > 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. > Generally, I felt it was easiest to "go with the flow". I am actually halfway through adding namespace support (surprise...!) and I will re-evaluate how useful these syntax features are when I'm done. (I don't know if I will include that feature in the respin for this series or not, it might be a just-after-freeze thing.) > > > Signed-off-by: John Snow <js...@redhat.com> > >
