Merge branch 'preserve-doc-indent' into 'main'

gdbus-codegen: preserve relative indentation in doc comments

Closes #3032

See merge request GNOME/glib!3536

gio/gdbus-2.0/codegen/codegen_docbook.py

@@ -20,6 +20,7 @@
 # Author: David Zeuthen <davidz@redhat.com>
 
 import re
+import textwrap
 from os import path
 
 from . import utils
@@ -340,12 +341,12 @@ class DocbookCodeGenerator:
         return s
 
     def expand_paras(self, s, expandParamsAndConstants):
-        s = self.expand(s, expandParamsAndConstants).strip()
+        s = textwrap.dedent(self.expand(s, expandParamsAndConstants)).rstrip()
         res = []
         if not s.startswith("<para>"):
             res.append("<para>")
         for line in s.split("\n"):
-            line = line.strip()
+            line = line.rstrip()
             if not line:
                 line = "</para><para>"
             res.append(line)

gio/gdbus-2.0/codegen/codegen_md.py

@@ -7,6 +7,7 @@ import os
 import re
 
 from . import utils
+import textwrap
 
 # Disable line length warnings as wrapping the templates would be hard
 # flake8: noqa: E501
@@ -22,8 +23,8 @@ class MdCodeGenerator:
     def _expand(self, s, expandParamsAndConstants):
         """Expands parameters and constant literals."""
         res = []
-        for line in s.split("\n"):
-            line = line.strip()
+        for line in textwrap.dedent(s).split("\n"):
+            line = line.rstrip()
             if line == "":
                 res.append("")
                 continue

gio/gdbus-2.0/codegen/codegen_rst.py

@@ -6,6 +6,7 @@ import os
 import re
 
 from . import utils
+import textwrap
 
 # Disable line length warnings as wrapping the templates would be hard
 # flake8: noqa: E501
@@ -21,8 +22,8 @@ class RstCodeGenerator:
     def _expand(self, s, expandParamsAndConstants):
         """Expands parameters and constant literals."""
         res = []
-        for line in s.split("\n"):
-            line = line.strip()
+        for line in textwrap.dedent(s).split("\n"):
+            line = line.rstrip()
             if line == "":
                 res.append("")
                 continue

gio/gdbus-2.0/codegen/parser.py

@@ -20,6 +20,7 @@
 # Author: David Zeuthen <davidz@redhat.com>
 
 import xml.parsers.expat
+import textwrap
 
 from . import dbustypes
 from .utils import print_error
@@ -64,14 +65,12 @@ class DBusXMLParser:
 
     def handle_comment(self, data):
         comment_state = DBusXMLParser.COMMENT_STATE_BEGIN
-        lines = data.split("\n")
+        lines = textwrap.dedent(data).split("\n")
         symbol = ""
         body = ""
         in_para = False
         params = {}
         for line in lines:
-            orig_line = line
-            line = line.lstrip()
             if comment_state == DBusXMLParser.COMMENT_STATE_BEGIN:
                 if len(line) > 0:
                     colon_index = line.find(": ")
@@ -95,7 +94,7 @@ class DBusXMLParser:
                         if not in_para:
                             body += "\n"
                             in_para = True
-                        body += f"{orig_line}\n"
+                        body += f"{line}\n"
                     else:
                         param = line[1:colon_index]
                         docs = line[colon_index + 2 :]
@@ -106,12 +105,12 @@ class DBusXMLParser:
                         if not in_para:
                             body += "\n"
                             in_para = True
-                        body += orig_line + "\n"
+                        body += line + "\n"
             elif comment_state == DBusXMLParser.COMMENT_STATE_BODY:
                 if len(line) > 0:
                     if not in_para:
                         in_para = True
-                    body += orig_line + "\n"
+                    body += line + "\n"
                 else:
                     if in_para:
                         body += "\n"

gio/tests/codegen.py

@@ -1340,6 +1340,48 @@ G_END_DECLS
         with open("test-org.project.Bar.Frobnicator.xml", "r") as f:
             self.assertTrue(ET.parse(f) is not None)
 
+    def test_indentation_preservation_in_comments(self):
+        """Test if the parser preserves relative indentation in XML comments"""
+        markup_list = """\
+- The mnemonic key activates the object if it is presently enabled onscreen.
+  This typically corresponds to the underlined letter within the widget.
+  Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for
+  a button."""
+
+        xml_contents = """
+        <node>
+          <interface name="org.project.Bar.Frobnicator">
+            <!-- GetKeyBinding:
+                 @index: 0-based index of the action to query.
+
+                 Gets the keybinding which can be used to activate this action, if one
+                 exists. The string returned should contain localized, human-readable,
+                 key sequences as they would appear when displayed on screen. It must
+                 be in the format "mnemonic;sequence;shortcut".
+
+                 - The mnemonic key activates the object if it is presently enabled onscreen.
+                   This typically corresponds to the underlined letter within the widget.
+                   Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for
+                   a button.
+
+                 If there is no key binding for this action, return "".
+            -->
+            <method name="GetKeyBinding">
+              <arg type="i" name="index" direction="in"/>
+              <arg type="s" direction="out"/>
+            </method>
+          </interface>
+        </node>
+        """
+        for format, ext in [("rst", "rst"), ("md", "md"), ("docbook", "xml")]:
+            res = self.runCodegenWithInterface(
+                xml_contents, f"--generate-{format}", "test"
+            )
+            self.assertFalse(res.err)
+            self.assertFalse(res.out)
+            with open(f"test-org.project.Bar.Frobnicator.{ext}", "r") as f:
+                self.assertIn(markup_list, f.read())
+
 
 if __name__ == "__main__":
     unittest.main(testRunner=taptestrunner.TAPTestRunner())