Skip to content
  • Markus Armbruster's avatar
    c1101028
    qapi: Fix bullet list markup in documentation · c1101028
    Markus Armbruster authored
    
    
    Peter Maydell's commit 100cc4fe explains:
    
        rST insists on a blank line before and after a bulleted list [...]
        Add some extra blank lines in the doc comments so they're
        acceptable rST input.
    
    It missed one in qapi/trace.json.
    
    Paolo Bonzini later added another instance in qapi/stats.json,
    providing further, if unintended, evidence for his quip that rST is
    the Perl of ASCII-based markups.
    
    Both are parsed as ordinary paragraph, resulting in garbled output.
    
    John Snow missed the need for a blank line when converting
    docs/devel/qapi-code-gen.txt to rST.
    
    Add the blank lines we need to get the bullet lists recognized as
    such.
    
    Kevin Wolf and Lukas Straub added two more, but indented.  Sphinx
    recognizes them as (indented) bullet lists.  The indentation looks
    slightly off.
    
    Insert a blank line and delete the extra indentation.
    
    Fixes: 100cc4fe (qapi: Add blank lines before bulleted lists)
    Fixes: 467ef823 (qmp: add filtering of statistics by target vCPU)
    Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
    Reviewed-by: default avatarVladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
    Reviewed-by: default avatarMarc-André Lureau <marcandre.lureau@redhat.com>
    Message-Id: <20230425064223.820979-10-armbru@redhat.com>
    [Fix of docs/devel/qapi-code-gen.rst squashed, commit message adjusted]
    c1101028
    qapi: Fix bullet list markup in documentation
    Markus Armbruster authored
    
    
    Peter Maydell's commit 100cc4fe explains:
    
        rST insists on a blank line before and after a bulleted list [...]
        Add some extra blank lines in the doc comments so they're
        acceptable rST input.
    
    It missed one in qapi/trace.json.
    
    Paolo Bonzini later added another instance in qapi/stats.json,
    providing further, if unintended, evidence for his quip that rST is
    the Perl of ASCII-based markups.
    
    Both are parsed as ordinary paragraph, resulting in garbled output.
    
    John Snow missed the need for a blank line when converting
    docs/devel/qapi-code-gen.txt to rST.
    
    Add the blank lines we need to get the bullet lists recognized as
    such.
    
    Kevin Wolf and Lukas Straub added two more, but indented.  Sphinx
    recognizes them as (indented) bullet lists.  The indentation looks
    slightly off.
    
    Insert a blank line and delete the extra indentation.
    
    Fixes: 100cc4fe (qapi: Add blank lines before bulleted lists)
    Fixes: 467ef823 (qmp: add filtering of statistics by target vCPU)
    Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
    Reviewed-by: default avatarVladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
    Reviewed-by: default avatarMarc-André Lureau <marcandre.lureau@redhat.com>
    Message-Id: <20230425064223.820979-10-armbru@redhat.com>
    [Fix of docs/devel/qapi-code-gen.rst squashed, commit message adjusted]
Loading