On Thu, Jun 27, 2024, 2:25 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@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. > Nope, misunderstood the instruction. Go right ahead. > > Signed-off-by: John Snow <js...@redhat.com> > > [Edited commit message and code comments per review --js] > > And I'll drop this line. > Vestigial remnants of a more optimistic time. > > Reviewed-by: Markus Armbruster <arm...@redhat.com> > >
