Re: [PATCH v3] qapi: Add documentation format validation

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:
>
>> Add explicit validation for QAPI documentation formatting rules:
>>
>> 1. Lines must not exceed 70 columns in width (including '# ' prefix)
>> 2. Sentences must be separated by two spaces
>>
>> Example sections are excluded, we don't require them to be <= 70,
>> that would be too restrictive.
>>
>> Example sections share common 80-columns recommendations (not
>> requirements).
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
>> ---
>>
>> Hi all!
>>
>> This substitutes my previous attempt
>>   "[PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences"
>> Supersedes: <20251011140441.297246-1-vsementsov@yandex-team.ru>
>>
>> v3:
>> 01: ignore example sections
>> other commits: dropped :)
>>
>> Of course, this _does not_ build on top of current master. v3 is
>> to be based on top of coming soon doc-cleanup series by Markus.

[...]

>> +        single_space_pattern = r'[.!?] [A-Z0-9]'
>
> This pattern matches possible sentence ends that lack a second space:
> sentence-ending punctuation, single space, capital letter or digit.
>
> The pattern avoids common false positives in the middle of a sentence,
> such as "i.e." here:
>
>     # Describes a block export, i.e. how single node should be exported on
>                                 ~~~~~
>
> Good.  There's still a risk of false positives, though: a capital letter
> need not be the start of a sentence, it could also be a proper noun, or
> the pronoun "I".  I figure the latter is vanishingly unlikely to occur
> in technical documentation.  Example of the former:
>
>     # @format: Extent type (e.g. FLAT or SPARSE)
>
> You filter these out below.
>
> Digits are even more ambiguous than capital letters: they can occur in
> the middle of a sentence as much as at the beginning.  Do they occur?
>
>     $ git-grep '\. [0-9]' \*.json
>     docs/interop/firmware.json:#                of SMRAM. 48MB should suffice for 4TB of guest-phys
>
> Yes, but only in a QAPI schema we don't actually parse.  We should
> probably update these to conform to conventions.  Not today.

Actually, we do parse it, but only in "make check".  See
docs/meson.build.  The cleanup series I just sent covers it.

Unfortunately, this adds another case for you.  In master:

    # @executable: Identifies the firmware executable. The @mode
    #              indicates whether there will be an associated
    #              NVRAM template present. The preferred
    #              corresponding QEMU command line options are
    #                  -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
    #                  -machine pflash0=pflash0
    #              or equivalent -blockdev instead of -drive. When
    #              @mode is @combined the executable must be
    #              cloned before use and configured with readonly=off.
    #              With QEMU versions older than 4.0, you have to use
    #                  -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format

My series cleans this up to

    # @executable: Identifies the firmware executable.  The @mode
    #     indicates whether there will be an associated NVRAM template
    #     present.  The preferred corresponding QEMU command line options
    #     are
    #
    #     ::
    #
    #         -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
    #         -machine pflash0=pflash0
    #
    #     or equivalent -blockdev instead of -drive.  When @mode is
    #     @combined the executable must be cloned before use and
    #     configured with readonly=off.  With QEMU versions older than
    #     4.0, you have to use
    #
    #     ::
    #
    #         -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format

This uses ReST markup for literal blocks.  There are two forms.

1. A paragraph containing just "::" starts a literal block.

2. A paragraph ending with "::" also starts one.

In either case, the block's contents is indented.

See https://docutils.sourceforge.io/docs/user/rst/quickref.html#literal-blocks
for more.

I think you need to switch literal mode on when you detect a qmp-example
directive or a literal block, and record the line's indentation.  switch
it off at the first line that is no more indented than the recorded
indentation.

[...]