docs: render markdown headings relative to their section

sphinx-markdown-builder pins rubric and option/signature headings to
level 3 while section titles use their absolute nesting depth. Nested
sphinx-click and sphinxcontrib-autoprogram sections therefore jump from
level 3 to 5 in the generated markdown, which the aggregated docs reject
(gldq HEAD-SKIP).

Override the markdown translator so those headings are rendered one
level below the enclosing section, keeping the API class/method layout
unchanged.

Signed-off-by: Eike Waldt <waldt@b1-systems.de>
On-behalf-of: SAP <eike.waldt@sap.com>
Assisted-by: Kilo:claude-sonnet-4-6

Author: yeoldegrove

docs/conf.py

@@ -1,5 +1,44 @@
+from typing import Any
+
 from sphinx.application import Sphinx
 
+
+def _register_relative_headings(app: Sphinx) -> None:
+    try:
+        from sphinx_markdown_builder.contexts import TitleContext
+        from sphinx_markdown_builder.translator import (
+            MarkdownTranslator,
+            pushing_context,
+        )
+    except ImportError:
+        return
+
+    class SectionRelativeMarkdownTranslator(MarkdownTranslator):  # type: ignore[misc]
+        """Render rubric and signature headings relative to their section.
+
+        sphinx-markdown-builder pins these headings to level 3 while section
+        titles use their absolute nesting depth. Nested sphinx-click and
+        sphinxcontrib-autoprogram sections then jump from level 3 to 5, which
+        breaks the aggregated documentation (gldq HEAD-SKIP).
+        """
+
+        @pushing_context
+        def visit_rubric(self, _node: Any) -> None:
+            self._push_context(TitleContext(self.status.section_level + 1))
+
+        @pushing_context
+        def visit_desc_signature(self, node: Any) -> None:
+            if self.config.markdown_anchor_signatures:
+                for anchor in node.get("ids", []):
+                    self._add_anchor(anchor)
+            level = self.status.section_level + 1
+            if node.get("class"):
+                level += 1
+            self._push_context(TitleContext(level))
+
+    app.set_translator("markdown", SectionRelativeMarkdownTranslator, override=True)
+
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -61,3 +100,4 @@
 # Add custom CSS
 def setup(app: Sphinx) -> None:
     app.add_css_file("custom.css")
+    _register_relative_headings(app)