On Fri, Jun 27, 2025, 5:52 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > This change removes special parsing for freeform sections and allows > > them to simply be unmodified rST syntax. The existing headings in the > > QAPI schema are adjusted to reflect the new paradigm. > > "Allows them to" suggests the patch enables use of rST headings. Is > this the case? Or do they just work, and this patch just switches > schema code to use them, and drops now unnecessary generator code? > > > > Tests and documentation are updated to match. > > > > Signed-off-by: John Snow <js...@redhat.com> > > [...] > > > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst > > index 231cc0fecf7..dfdbeac5a5a 100644 > > --- a/docs/devel/qapi-code-gen.rst > > +++ b/docs/devel/qapi-code-gen.rst > > @@ -876,25 +876,35 @@ structuring content. > Documentation comments > ---------------------- > > A multi-line comment that starts and ends with a ``##`` line is a > documentation comment. > > If the documentation comment starts like :: > > ## > # @SYMBOL: > > it documents the definition of SYMBOL, else it's free-form > documentation. > > See below for more on `Definition documentation`_. > > Free-form documentation may be used to provide additional text and > structuring content. > > > > Headings and subheadings > > ~~~~~~~~~~~~~~~~~~~~~~~~ > > > > -A free-form documentation comment containing a line which starts with > > -some ``=`` symbols and then a space defines a section heading:: > > +Free-form documentation does not start with ``@SYMBOL`` and can contain > > +arbitrary rST markup. Headings can be marked up using the standard rST > > +syntax:: > > Nothing stops you from using such markup in definition documentation. > It's probably a bad idea, though. > > I think it's easiest not to talk about the two kinds of doc blocks here > at all. Scratch the first sentence? > Sure. > > > > ## > > - # = This is a top level heading > > + # ************************* > > + # This is a level 2 heading > > + # ************************* > > # > > # This is a free-form comment which will go under the > > # top level heading. > > ## > > > > ## > > - # == This is a second level heading > > + # This is a third level heading > > + # ============================== > > + # > > + # Level 4 > > + # _______ > > + # > > + # Level 5 > > + # ^^^^^^^ > > + # > > + # Level 6 > > + # """"""" > > ## > > > > -A heading line must be the first line of the documentation > > -comment block. > > - > > -Section headings must always be correctly nested, so you can only > > -define a third-level heading inside a second-level heading, and so on. > > +Level 1 headings are reserved for use by the generated documentation > > +page itself, leaving level 2 as the highest level that should be used. > > > > > > Documentation markup > > [...] > >
