d461c279 | 26-Jun-2024 |
John Snow <jsnow@redhat.com> |
qapi: convert "Note" sections to plain rST
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP
qapi: convert "Note" sections to plain rST
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.
Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation. Markup is also re-aligned to the de-facto standard of 3 spaces for directives.
Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:
.. note:: lorem ipsum ... ... dolor sit amet ... ... consectetur adipiscing elit ...
... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol () in the title bar for rendered HTML docs.
See https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions for examples of each directive/admonition in use.
These are rendered in orange:
.. Attention:: ... .. Caution:: ... .. WARNING:: ...
These are rendered in red:
.. DANGER:: ... .. Error:: ...
These are rendered in green:
.. Hint:: ... .. Important:: ... .. Tip:: ...
These are rendered in blue:
.. Note:: ... .. admonition:: custom title
admonition body text
This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example.
NOTE: Because qapidoc.py does not attempt to preserve source ordering of sections, the conversion of Notes from a "tagged section" to an "untagged section" means that rendering order for some notes *may change* as a result of this patch. The forthcoming qapidoc.py rewrite strictly preserves source ordering in the rendered documentation, so this issue will be rectified in the new generator.
Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
83deda87 | 26-Jun-2024 |
John Snow <jsnow@redhat.com> |
qapi/parser: fix comment parsing immediately following a doc block
If a comment immediately follows a doc block, the parser doesn't ignore that token appropriately. Fix that.
e.g.
> ## > # = Hello
qapi/parser: fix comment parsing immediately following a doc block
If a comment immediately follows a doc block, the parser doesn't ignore that token appropriately. Fix that.
e.g.
> ## > # = Hello World! > ## > > # I'm a comment!
will break the parser, because it does not properly ignore the comment token if it immediately follows a doc block.
Fixes: 3d035cd2cca6 (qapi: Rewrite doc comment parser) Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-7-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
939c639e | 26-Jun-2024 |
John Snow <jsnow@redhat.com> |
qapi/parser: preserve indentation in QAPIDoc sections
Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py that
qapi/parser: preserve indentation in QAPIDoc sections
Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py that removes indentation the same way get_doc_indented() did.
This is being done for the benefit of a new qapidoc generator which requires that indentation in argument and features sections are preserved.
Prior to this patch, a section like this:
``` @name: lorem ipsum dolor sit amet consectetur adipiscing elit ```
would have its body text be parsed into:
``` lorem ipsum dolor sit amet consectetur adipiscing elit ```
We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment into:
``` lorem ipsum dolor sit amet consectetur adipiscing elit ```
This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as:
``` :arg type name: lorem ipsum dolor sit amet consectetur apidiscing elit ```
...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup.
This understandably breaks the existing qapidoc.py; so a new function is added there to dedent the text for compatibility. Once the new generator is merged, this function will not be needed any longer and can be dropped.
I verified this patch changes absolutely nothing by comparing the md5sums of the QMP ref html pages both before and after the change, so it's certified inert. QAPI test output has been updated to reflect the new strategy of preserving indents for rST.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-6-jsnow@redhat.com> [Lost commit message paragraph restored] Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
285a8f20 | 16-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Simplify QAPISchemaVariants @tag_member
For union types, the tag member is known only after .check().
We used to code this in a simple way: QAPISchemaVariants attribute .tag_member was None f
qapi: Simplify QAPISchemaVariants @tag_member
For union types, the tag member is known only after .check().
We used to code this in a simple way: QAPISchemaVariants attribute .tag_member was None for union types until .check().
Since this complicated typing, recent commit "qapi/schema: fix typing for QAPISchemaVariants.tag_member" hid it behind a property.
The previous commit lets us treat .tag_member just like the other attributes that become known only in .check(): declare, but don't initialize it in .__init__().
Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
8152bc7d | 15-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Move conditional code from QAPISchemaVariants to its subtypes
QAPISchemaVariants.check()'s code is almost entirely conditional on union vs. alternate type.
Move the conditional code to QAPISc
qapi: Move conditional code from QAPISchemaVariants to its subtypes
QAPISchemaVariants.check()'s code is almost entirely conditional on union vs. alternate type.
Move the conditional code to QAPISchemaBranches.check() and QAPISchemaAlternatives.check(), where the conditions are always satisfied.
Attribute QAPISchemaVariants.tag_name is now only used by QAPISchemaBranches. Move it there.
Refactor the three types' .__init__() to make them a bit simpler.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
e0a28f39 | 15-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Rename QAPISchemaAlternateType.variants to .alternatives
A previous commit narrowed the type of QAPISchemaAlternateType.variants from QAPISchemaVariants to QAPISchemaAlternatives. Rename it t
qapi: Rename QAPISchemaAlternateType.variants to .alternatives
A previous commit narrowed the type of QAPISchemaAlternateType.variants from QAPISchemaVariants to QAPISchemaAlternatives. Rename it to .alternatives.
Same for .__init__() parameter @variants.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
3ff2a5a3 | 15-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Rename QAPISchemaObjectType.variants to .branches
A previous commit narrowed the type of QAPISchemaObjectType.variants from QAPISchemaVariants to QAPISchemaBranches. Rename it to .branches.
qapi: Rename QAPISchemaObjectType.variants to .branches
A previous commit narrowed the type of QAPISchemaObjectType.variants from QAPISchemaVariants to QAPISchemaBranches. Rename it to .branches.
Same for .__init__() parameter @variants.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
d1da8af8 | 15-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Rename visitor parameter @variants to @branches
The previous commit narrowed the type of .visit_object_type() parameter @variants from QAPISchemaVariants to QAPISchemaBranches. Rename it to @b
qapi: Rename visitor parameter @variants to @branches
The previous commit narrowed the type of .visit_object_type() parameter @variants from QAPISchemaVariants to QAPISchemaBranches. Rename it to @branches.
Same for .visit_object_type_flat().
A few of these pass @branches to helper functions: QAPISchemaGenRSTVisitor.visit_object_type() to ._nodes_for_members() and ._nodes_for_variant_when(), and QAPISchemaGenVisitVisitor.visit_object_type() to gen_visit_object_members(). Rename the helpers' @variants parameters to @branches as well.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
060b5a93 | 15-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Dumb down QAPISchema.lookup_entity()
QAPISchema.lookup_entity() takes an optional type argument, a subtype of QAPISchemaDefinition, and returns that type or None. Callers can use this to save
qapi: Dumb down QAPISchema.lookup_entity()
QAPISchema.lookup_entity() takes an optional type argument, a subtype of QAPISchemaDefinition, and returns that type or None. Callers can use this to save themselves an isinstance() test.
The only remaining user of this convenience feature is .lookup_type(). But we don't actually save anything anymore there: we still need the isinstance() to help mypy over the hump.
Drop the .lookup_entity() argument, and adjust .lookup_type().
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-26-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> [Commit message typo fixed]
show more ...
|
99e75d8c | 15-Mar-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Tighten check whether implicit object type already exists
Entities with names starting with q_obj_ are implicit object types. Therefore, QAPISchema._make_implicit_object_type()'s .lookup_entit
qapi: Tighten check whether implicit object type already exists
Entities with names starting with q_obj_ are implicit object types. Therefore, QAPISchema._make_implicit_object_type()'s .lookup_entity() can only return a QAPISchemaObjectType. Assert that.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-25-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: John Snow <jsnow@redhat.com>
show more ...
|
8d413dbd | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/schema: remove unnecessary asserts
With strict typing enabled, these runtime statements aren't necessary anymore; we can prove them statically.
Signed-off-by: John Snow <jsnow@redhat.com> Revi
qapi/schema: remove unnecessary asserts
With strict typing enabled, these runtime statements aren't necessary anymore; we can prove them statically.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-24-armbru@redhat.com>
show more ...
|
aa1fed9f | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/schema: turn on mypy strictness
This patch can be rolled in with the previous one once the series is ready for merge, but for work-in-progress' sake, it's separate here.
Signed-off-by: John Sn
qapi/schema: turn on mypy strictness
This patch can be rolled in with the previous one once the series is ready for merge, but for work-in-progress' sake, it's separate here.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-23-armbru@redhat.com>
show more ...
|
4ed3fe08 | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/schema: add type hints
This patch only adds type hints, which aren't utilized at runtime and don't change the behavior of this module in any way.
In a scant few locations, type hints are remov
qapi/schema: add type hints
This patch only adds type hints, which aren't utilized at runtime and don't change the behavior of this module in any way.
In a scant few locations, type hints are removed where no longer necessary due to inference power from typing all of the rest of creation; and any type hints that no longer need string quotes are changed.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-22-armbru@redhat.com>
show more ...
|
d5e2f3d0 | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/parser.py: assert member.info is present in connect_member
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbr
qapi/parser.py: assert member.info is present in connect_member
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-21-armbru@redhat.com>
show more ...
|
7c6e4464 | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/parser: demote QAPIExpression to Dict[str, Any]
Dict[str, object] is a stricter type, but with the way that code is currently arranged, it is infeasible to enforce this strictness.
In particul
qapi/parser: demote QAPIExpression to Dict[str, Any]
Dict[str, object] is a stricter type, but with the way that code is currently arranged, it is infeasible to enforce this strictness.
In particular, although expr.py's entire raison d'être is normalization and type-checking of QAPI Expressions, that type information is not "remembered" in any meaningful way by mypy because each individual expression is not downcast to a specific expression type that holds all the details of each expression's unique form.
As a result, all of the code in schema.py that deals with actually creating type-safe specialized structures has no guarantee (myopically) that the data it is being passed is correct.
There are two ways to solve this:
(1) Re-assert that the incoming data is in the shape we expect it to be, or (2) Disable type checking for this data.
(1) is appealing to my sense of strictness, but I gotta concede that it is asinine to re-check the shape of a QAPIExpression in schema.py when expr.py has just completed that work at length. The duplication of code and the nightmare thought of needing to update both locations if and when we change the shape of these structures makes me extremely reluctant to go down this route.
(2) allows us the chance to miss updating types in the case that types are updated in expr.py, but it *is* an awful lot simpler and, importantly, gets us closer to type checking schema.py *at all*. Something is better than nothing, I'd argue.
So, do the simpler dumber thing and worry about future strictness improvements later.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-20-armbru@redhat.com>
show more ...
|
7e09dd68 | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/schema: assert inner type of QAPISchemaVariants in check_clash()
QAPISchemaVariant's "variants" field is typed as List[QAPISchemaVariant], where the typing for QAPISchemaVariant allows its type
qapi/schema: assert inner type of QAPISchemaVariants in check_clash()
QAPISchemaVariant's "variants" field is typed as List[QAPISchemaVariant], where the typing for QAPISchemaVariant allows its type field to be any QAPISchemaType.
However, QAPISchemaVariant expects that all of its variants contain the narrower QAPISchemaObjectType. This relationship is enforced at runtime in QAPISchemaVariants.check(). This relationship is not embedded in the type system though, so QAPISchemaVariants.check_clash() needs to re-assert this property in order to call QAPISchemaVariant.type.check_clash().
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-19-armbru@redhat.com>
show more ...
|
583f4d6f | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/schema: fix typing for QAPISchemaVariants.tag_member
There are two related changes here:
(1) We need to perform type narrowing for resolving the type of tag_member during check(), and
(2)
qapi/schema: fix typing for QAPISchemaVariants.tag_member
There are two related changes here:
(1) We need to perform type narrowing for resolving the type of tag_member during check(), and
(2) tag_member is a delayed initialization field, but we can hide it behind a property that raises an Exception if it's called too early. This simplifies the typing in quite a few places and avoids needing to assert that the "tag_member is not None" at a dozen callsites, which can be confusing and suggest the wrong thing to a drive-by contributor.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-18-armbru@redhat.com>
show more ...
|
9beda22d | 15-Mar-2024 |
John Snow <jsnow@redhat.com> |
qapi/schema: Don't initialize "members" with `None`
Declare, but don't initialize the "members" field with type List[QAPISchemaObjectTypeMember].
This simplifies the typing from what would otherwis
qapi/schema: Don't initialize "members" with `None`
Declare, but don't initialize the "members" field with type List[QAPISchemaObjectTypeMember].
This simplifies the typing from what would otherwise be Optional[List[T]] to merely List[T]. This removes the need to add assertions to several callsites that this value is not None - which it never will be after the delayed initialization in check() anyway.
The type declaration without initialization trick will cause accidental uses of this field prior to full initialization to raise an AttributeError.
(Note that it is valid to have an empty members list, see the internal q_empty object as an example. For this reason, we cannot use the empty list as a replacement test for full initialization and instead rely on the _checked/_check_complete fields.)
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240315152301.3621858-17-armbru@redhat.com>
show more ...
|