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 ...
|
3a025d3d | 27-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: New documentation section tag "Errors"
We use section "Returns" for documenting both success and error response of commands.
I intend to generate better command success response documentation
qapi: New documentation section tag "Errors"
We use section "Returns" for documenting both success and error response of commands.
I intend to generate better command success response documentation. Easier when "Returns" documents just he success response.
Create new section tag "Errors". The next two commits will move error response documentation from "Returns" sections to "Errors" sections.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-4-armbru@redhat.com>
show more ...
|
adb0193b | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Divorce QAPIDoc from QAPIParseError
QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to
qapi: Divorce QAPIDoc from QAPIParseError
QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to be the current comment line. Servicable, but action at a distance.
The commit before previous moved most uses of QAPIParseError from QAPIDoc to QAPIParser. There are just three left. Convert them to QAPISemError. This involves passing info to a few methods. Then drop the reference to QAPIParser.
The three errors lose the column number. Not really interesting here: it's the comment line's indentation.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-17-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
629c5075 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Reject multiple and empty feature descriptions
The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-f
qapi: Reject multiple and empty feature descriptions
The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-features. Recognize "Features:" lines anywhere. A second one is an error.
A 'Features:' line without any features is useless, but not an error. Make it an error. This makes detecting a second "Features:" line easier.
qapi/run-state.json actually has an instance of this since commit fe17522d854 (qapi: Remove deprecated 'singlestep' member of StatusInfo). Clean it up.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
0b82a744 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Merge adjacent untagged sections
The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral
qapi: Merge adjacent untagged sections
The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral change in the next commit.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-14-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
66227e90 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Recognize section tags and 'Features:' only after blank line
Putting a blank line before section tags and 'Features:' is good, existing practice. Enforce it.
Signed-off-by: Markus Armbruster
qapi: Recognize section tags and 'Features:' only after blank line
Putting a blank line before section tags and 'Features:' is good, existing practice. Enforce it.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-12-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
56c64dd6 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Reject section heading in the middle of a doc comment
docs/devel/qapi-code-gen.txt claims "A heading line must be the first line of the documentation comment block" since commit 55ec69f8b16 (d
qapi: Reject section heading in the middle of a doc comment
docs/devel/qapi-code-gen.txt claims "A heading line must be the first line of the documentation comment block" since commit 55ec69f8b16 (docs/devel/qapi-code-gen.txt: Update to new rST backend conventions). Not true, we have code to make it work anywhere in a free-form doc comment: commit dcdc07a97cb (qapi: Make section headings start a new doc comment block).
Make it true, for simplicity's sake.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-10-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
31c54b92 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Rename QAPIDoc.Section.name to .tag
Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag.
qapi: Rename QAPIDoc.Section.name to .tag
Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-9-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
573e2223 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Improve error message for empty doc sections
Improve the message for an empty tagged section from
empty doc section 'Note'
to
text required after 'Note:'
and the message for an emp
qapi: Improve error message for empty doc sections
Improve the message for an empty tagged section from
empty doc section 'Note'
to
text required after 'Note:'
and the message for an empty argument or feature description from
empty doc section 'foo'
to
text required after '@foo:'
Improve the error position to refer to the beginning of the empty section instead of its end.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
bf00dc19 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Improve error position for bogus invalid "Returns" section
When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Po
qapi: Improve error position for bogus invalid "Returns" section
When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Point to the "Returns" section instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
15333abe | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Improve error position for bogus argument descriptions
When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus arg
qapi: Improve error position for bogus argument descriptions
When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus argument description instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-6-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
0ba2915b | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
tests/qapi-schema: Cover 'Features:' not followed by descriptions
A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that ma
tests/qapi-schema: Cover 'Features:' not followed by descriptions
A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that makes rejecting duplicate 'Features:' easier.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-4-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
fc68b9ff | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
tests/qapi-schema: Cover duplicate 'Features:' line
We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section.
If it was followed by feature description,
tests/qapi-schema: Cover duplicate 'Features:' line
We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section.
If it was followed by feature description, we'd reject that like "description of '@feat2:' follows a section". Less than clear.
To be improved shortly.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|