[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 05/21] qapi/parser: preserve indentation in QAPIDoc sectio
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v2 05/21] qapi/parser: preserve indentation in QAPIDoc sections |
Date: |
Thu, 27 Jun 2024 08:25:03 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
John Snow <jsnow@redhat.com> writes:
> 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'll restore this paragraph if you don't mind:
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 <jsnow@redhat.com>
> [Edited commit message and code comments per review --js]
And I'll drop this line.
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
- [PATCH v2 03/21] docs/qapidoc: remove unused intersperse function, (continued)
- [PATCH v2 03/21] docs/qapidoc: remove unused intersperse function, John Snow, 2024/06/26
- [PATCH v2 04/21] docs/qapidoc: delint a tiny portion of the module, John Snow, 2024/06/26
- [PATCH v2 05/21] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/26
- [PATCH v2 06/21] qapi/parser: fix comment parsing immediately following a doc block, John Snow, 2024/06/26
- [PATCH v2 07/21] docs/qapidoc: fix nested parsing under untagged sections, John Snow, 2024/06/26
- [PATCH v2 08/21] qapi: fix non-compliant JSON examples, John Snow, 2024/06/26
- [PATCH v2 09/21] qapi: nail down convention that Errors sections are lists, John Snow, 2024/06/26
- [PATCH v2 11/21] qapi: update prose in note blocks, John Snow, 2024/06/26