From f64e753149a0472e381246f0e06e5b293aa40541 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:08 -0400 Subject: qapi: linter fixups Fix minor irritants to pylint/flake8 et al. (Yes, these need to be guarded by the Python tests. That's a work in progress, a series that's quite likely to follow once I finish this Sphinx project. Please pardon the temporary irritation.) Signed-off-by: John Snow Reviewed-by: Markus Armbruster Message-ID: <20240626222128.406106-3-jsnow@redhat.com> Signed-off-by: Markus Armbruster --- scripts/qapi/introspect.py | 8 ++++---- scripts/qapi/schema.py | 6 +++--- scripts/qapi/visit.py | 5 +++-- 3 files changed, 10 insertions(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py index 86c075a..ac14b20 100644 --- a/scripts/qapi/introspect.py +++ b/scripts/qapi/introspect.py @@ -27,8 +27,8 @@ from .gen import QAPISchemaMonolithicCVisitor from .schema import ( QAPISchema, QAPISchemaAlternatives, - QAPISchemaBranches, QAPISchemaArrayType, + QAPISchemaBranches, QAPISchemaBuiltinType, QAPISchemaEntity, QAPISchemaEnumMember, @@ -233,9 +233,9 @@ const QLitObject %(c_name)s = %(c_string)s; typ = type_int elif (isinstance(typ, QAPISchemaArrayType) and typ.element_type.json_type() == 'int'): - type_intList = self._schema.lookup_type('intList') - assert type_intList - typ = type_intList + type_intlist = self._schema.lookup_type('intList') + assert type_intlist + typ = type_intlist # Add type to work queue if new if typ not in self._used_types: self._used_types.append(typ) diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index 721c470..d65c35f 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -730,6 +730,7 @@ class QAPISchemaVariants: for v in self.variants: v.set_defined_in(name) + # pylint: disable=unused-argument def check( self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember] ) -> None: @@ -1166,7 +1167,7 @@ class QAPISchema: defn.info, "%s is already defined" % other_defn.describe()) self._entity_dict[defn.name] = defn - def lookup_entity(self,name: str) -> Optional[QAPISchemaEntity]: + def lookup_entity(self, name: str) -> Optional[QAPISchemaEntity]: return self._entity_dict.get(name) def lookup_type(self, name: str) -> Optional[QAPISchemaType]: @@ -1302,11 +1303,10 @@ class QAPISchema: name = 'q_obj_%s-%s' % (name, role) typ = self.lookup_entity(name) if typ: - assert(isinstance(typ, QAPISchemaObjectType)) + assert isinstance(typ, QAPISchemaObjectType) # The implicit object type has multiple users. This can # only be a duplicate definition, which will be flagged # later. - pass else: self._def_definition(QAPISchemaObjectType( name, info, None, ifcond, None, None, members, None)) diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py index e766aca..12f92e4 100644 --- a/scripts/qapi/visit.py +++ b/scripts/qapi/visit.py @@ -280,8 +280,9 @@ bool visit_type_%(c_name)s(Visitor *v, const char *name, abort(); default: assert(visit_is_input(v)); - error_setg(errp, "Invalid parameter type for '%%s', expected: %(name)s", - name ? name : "null"); + error_setg(errp, + "Invalid parameter type for '%%s', expected: %(name)s", + name ? name : "null"); /* Avoid passing invalid *obj to qapi_free_%(c_name)s() */ g_free(*obj); *obj = NULL; -- cgit v1.1 From 939c639e1d7c1d78bcc262368ab1fb78f09d0bfe Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:11 -0400 Subject: 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 Reviewed-by: Markus Armbruster Message-ID: <20240626222128.406106-6-jsnow@redhat.com> [Lost commit message paragraph restored] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 7b13a58..1ef1f85 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -448,7 +448,7 @@ class QAPISchemaParser: indent = must_match(r'\s*', line).end() if not indent: return line - doc.append_line(line[indent:]) + doc.append_line(line) prev_line_blank = False while True: self.accept(False) @@ -465,7 +465,7 @@ class QAPISchemaParser: self, "unexpected de-indent (expected at least %d spaces)" % indent) - doc.append_line(line[indent:]) + doc.append_line(line) prev_line_blank = True def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]: -- cgit v1.1 From 83deda876940116d31bf47c51e62e0fe625e8655 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:12 -0400 Subject: 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 Reviewed-by: Markus Armbruster Message-ID: <20240626222128.406106-7-jsnow@redhat.com> Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 1ef1f85..c3d20cc 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -583,7 +583,7 @@ class QAPISchemaParser: line = self.get_doc_line() first = False - self.accept(False) + self.accept() doc.end() return doc -- cgit v1.1 From d461c2797374e0becc5227cdc099d85bc329b236 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:16 -0400 Subject: qapi: convert "Note" sections to plain rST MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Acked-by: Stefan Hajnoczi [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'scripts') diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c3d20cc..0a13f0f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -547,6 +547,21 @@ class QAPISchemaParser: r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', line): # tagged section + + # TODO: Remove this error sometime in 2025 or so + # after we've fully transitioned to the new qapidoc + # generator. + + # See commit message for more markup suggestions O:-) + if 'Note' in match.group(1): + emsg = ( + f"The '{match.group(1)}' section is no longer " + "supported. Please use rST's '.. note::' or " + "'.. admonition:: notes' directives, or another " + "suitable admonition instead." + ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info, match.group(1)) text = line[match.end():] if text: -- cgit v1.1 From 65fa48c79f20a37c7204f9e43dd7cc3058aa066c Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:19 -0400 Subject: qapi/parser: don't parse rST markup as section headers The double-colon synax is rST formatting that precedes a literal code block. We do not want to capture these as QAPI-specific sections. Coerce blocks that start with e.g. "Example::" to be parsed as untagged paragraphs instead of special tagged sections. Signed-off-by: John Snow Message-ID: <20240626222128.406106-14-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Indentation tweaked for consistency] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 0a13f0f..6ad5663 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -544,10 +544,15 @@ class QAPISchemaParser: line = self.get_doc_indented(doc) no_more_args = True elif match := re.match( - r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', - line): + r'(Returns|Errors|Since|Notes?|Examples?|TODO)' + r'(?!::): *', + line, + ): # tagged section + # Note: "sections" with two colons are left alone as + # rST markup and not interpreted as a section heading. + # TODO: Remove this error sometime in 2025 or so # after we've fully transitioned to the new qapidoc # generator. -- cgit v1.1