From 705703dde4e7746ff0470d46603f1612adc32630 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 11 Nov 2026 16:26:44 +0100 Subject: [PATCH 1/2] 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 On-behalf-of: SAP Assisted-by: Kilo:claude-sonnet-4-6 --- docs/conf.py | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 45b219c5..41ed2ecb 100644 --- a/docs/conf.py +++ b/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) From 937885c67115c43cb89b7936a9865de36b5906bf Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 11 Nov 2026 16:57:17 +0100 Subject: [PATCH 2/2] docs(release): classify code block Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/how-to/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/release.md b/docs/how-to/release.md index 6ee2c7ea..01f17e7a 100644 --- a/docs/how-to/release.md +++ b/docs/how-to/release.md @@ -58,7 +58,7 @@ command line. Or in `requirements.txt`: - ``` + ```text gardenlinux @ git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0 ```