From 9ca404f0043d63043bfed3af8da3adedc062cb13 Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:05 -0400 Subject: docs/qapi-domain: add :namespace: override option Akin to the :module: override option, the :namespace: options allows you to forcibly override the contextual namespace associatied with a definition. We don't necessarily actually need this, but I felt compelled to stick close to how the Python domain works that offers context overrides. As of this commit, it is possible to add e.g. ":namespace: QMP" to any QAPI directive to forcibly associate that definition with a given namespace. Signed-off-by: John Snow Message-ID: <20250313044312.189276-5-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 1475870..51b2832 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -466,6 +466,8 @@ QAPI standard options All QAPI directives -- *except* for module -- support these common options. +* ``:namespace: name`` -- This option allows you to override the + namespace association of a given definition. * ``:module: modname`` -- Borrowed from the Python domain, this option allows you to override the module association of a given definition. * ``:since: x.y`` -- Allows the documenting of "Since" information, which is -- cgit v1.1 From 7c7247b252dd8b3911b96451c0eaaebbc6ac0af0 Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:06 -0400 Subject: docs/qapi-domain: add qapi:namespace directive Add a new directive that marks the beginning of a QAPI "namespace", for example; "QMP", "QGA" or "QSD". This directive will associate all subsequent QAPI directives in a document with the specified namespace. This does not change the visual display of any of the definitions or index entries, but does change the "Fully Qualified Name" inside the QAPI domain's object table. This allows for two different "namespaces" to define entities with otherwise identical names -- which will come in handy for documenting both QEMU QMP and the QEMU Storage Daemon. Signed-off-by: John Snow Message-ID: <20250313044312.189276-6-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 51b2832..73e13ab 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -464,7 +464,8 @@ removed in a future version. QAPI standard options --------------------- -All QAPI directives -- *except* for module -- support these common options. +All QAPI directives -- *except* for namespace and module -- support +these common options. * ``:namespace: name`` -- This option allows you to override the namespace association of a given definition. @@ -482,6 +483,23 @@ All QAPI directives -- *except* for module -- support these common options. production code. +qapi:namespace +-------------- + +The ``qapi:namespace`` directive marks the start of a QAPI namespace. It +does not take a content body, nor any options. All subsequent QAPI +directives are associated with the most recent namespace. This affects +the definition's "fully qualified name", allowing two different +namespaces to create an otherwise identically named definition. + +Example:: + + .. qapi:namespace:: QMP + + +This directive has no visible effect. + + qapi:module ----------- -- cgit v1.1 From 7127e14f15fc52b436eb63e482a9f117bd4346d2 Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:08 -0400 Subject: docs/qapi_domain: add namespace support to cross-references This patch does three things: 1. Record the current namespace context in pending_xrefs so it can be used for link resolution later, 2. Pass that recorded namespace context to find_obj() when resolving a reference, and 3. Wildly and completely rewrite find_obj(). cross-reference support is expanded to tolerate the presence or absence of either namespace or module, and to cope with the presence or absence of contextual information for either. References now work like this: 1. If the explicit reference target is recorded in the domain's object registry, we link to that target and stop looking. We do this lookup regardless of how fully qualified the target is, which allows direct references to modules (which don't have a module component to their names) or direct references to definitions that may or may not belong to a namespace or module. 2. If contextual information is available from qapi:namespace or qapi:module directives, try using those components to find a direct match to the implied target name. 3. If both prior lookups fail, generate a series of regular expressions looking for wildcard matches in order from most to least specific. Any explicitly provided components (namespace, module) *must* match exactly, but both contextual and entirely omitted components are allowed to differ from the search result. Note that if more than one result is found, Sphinx will emit a warning (a build error for QEMU) and list all of the candidate references. The practical upshot is that in the large majority of cases, namespace and module information is not required when creating simple `references` to definitions from within the same context -- even when identical definitions exist in other contexts. Even when using simple `references` from elsewhere in the QEMU documentation manual, explicit namespace info is not required if there is only one definition by that name. Disambiguation *will* be required from outside of the QAPI documentation when referencing e.g. block-core definitions, which are shared between QEMU QMP and the QEMU Storage Daemon. In that case, there are two options: A: References can be made partially or fully explicit, e.g. `QMP:block-dirty-bitmap-add` will link to the QEMU version of the definition, while `QSD:block-dirty-bitmap-add` would link to the QSD version. B: If all of the references in a document are intended to go to the same place, you can insert a "qapi:namespace:: QMP" directive to influence the fuzzy-searching for later references. Signed-off-by: John Snow Message-ID: <20250313044312.189276-8-jsnow@redhat.com> Acked-by: Markus Armbruster [Commit message typo fixed] Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 73e13ab..4705ba2 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -400,11 +400,10 @@ Namespaces Mimicking the `Python domain target specification syntax `_, QAPI allows you to specify the fully qualified path for a data -type. QAPI enforces globally unique names, so it's unlikely you'll need -this specific feature, but it may be extended in the near future to -allow referencing identically named commands and data types from -different utilities; i.e. QEMU Storage Daemon vs QMP. +type. +* A namespace can be explicitly provided; + e.g. ``:qapi:type:`QMP:BitmapSyncMode`` * A module can be explicitly provided; ``:qapi:type:`block-core.BitmapSyncMode``` will render to: :qapi:type:`block-core.BitmapSyncMode` @@ -413,6 +412,28 @@ different utilities; i.e. QEMU Storage Daemon vs QMP. will render to: :qapi:type:`~block-core.BitmapSyncMode` +Target resolution +----------------- + +Any cross-reference to a QAPI type, whether using the ```any``` style of +reference or the more explicit ```:qapi:any:`target``` syntax, allows +for the presence or absence of either the namespace or module +information. + +When absent, their value will be inferred from context by the presence +of any ``qapi:namespace`` or ``qapi:module`` directives preceding the +cross-reference. + +If no results are found when using the inferred values, other +namespaces/modules will be searched as a last resort; but any explicitly +provided values must always match in order to succeed. + +This allows for efficient cross-referencing with a minimum of syntax in +the large majority of cases, but additional context or namespace markup +may be required outside of the QAPI reference documents when linking to +items that share a name across multiple documented QAPI schema. + + Custom link text ---------------- @@ -492,6 +513,11 @@ directives are associated with the most recent namespace. This affects the definition's "fully qualified name", allowing two different namespaces to create an otherwise identically named definition. +This directive also influences how reference resolution works for any +references that do not explicity specify a namespace, so this directive +can be used to nudge references into preferring targets from within that +namespace. + Example:: .. qapi:namespace:: QMP -- cgit v1.1 From d85f7efe1f16c51b9c016ebc79f7c4081486642e Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:11 -0400 Subject: docs: disambiguate references in qapi-domain.rst Before we enable the QGA and QSD namespaces, we need to disambiguate some of the references that would become ambiguous as a result! Signed-off-by: John Snow Message-ID: <20250313044312.189276-11-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 4705ba2..a748529 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -385,13 +385,13 @@ Type names in references can be surrounded by brackets, like ``[typename]``, to indicate an array of that type. The cross-reference will apply only to the type name between the brackets. For example; ``:qapi:type:`[Qcow2BitmapInfoFlags]``` renders to: -:qapi:type:`[Qcow2BitmapInfoFlags]` +:qapi:type:`[QMP:Qcow2BitmapInfoFlags]` To indicate an optional argument/member in a field list, the type name can be suffixed with ``?``. The cross-reference will be transformed to "type, Optional" with the link applying only to the type name. For example; ``:qapi:type:`BitmapSyncMode?``` renders to: -:qapi:type:`BitmapSyncMode?` +:qapi:type:`QMP:BitmapSyncMode?` Namespaces @@ -405,11 +405,11 @@ type. * A namespace can be explicitly provided; e.g. ``:qapi:type:`QMP:BitmapSyncMode`` * A module can be explicitly provided; - ``:qapi:type:`block-core.BitmapSyncMode``` will render to: - :qapi:type:`block-core.BitmapSyncMode` + ``:qapi:type:`QMP:block-core.BitmapSyncMode``` will render to: + :qapi:type:`QMP:block-core.BitmapSyncMode` * If you don't want to display the "fully qualified" name, it can be - prefixed with a tilde; ``:qapi:type:`~block-core.BitmapSyncMode``` - will render to: :qapi:type:`~block-core.BitmapSyncMode` + prefixed with a tilde; ``:qapi:type:`~QMP:block-core.BitmapSyncMode``` + will render to: :qapi:type:`~QMP:block-core.BitmapSyncMode` Target resolution @@ -444,7 +444,7 @@ using the ``custom text `` syntax. For example, ``:qapi:cmd:`Merge dirty bitmaps ``` will render as: :qapi:cmd:`Merge dirty -bitmaps ` +bitmaps ` Directives -- cgit v1.1