[ENH/FIX] Support headings in nested parse

docs/conf.py

@@ -136,7 +136,7 @@
     },
 }
 myst_number_code_blocks = ["typescript"]
-myst_heading_anchors = 2
+myst_heading_anchors = 3
 myst_footnote_transition = True
 myst_dmath_double_inline = True
 myst_enable_checkboxes = True

docs/syntax/cross-referencing.md

@@ -74,9 +74,9 @@ The anchor "slugs" are created according to the [GitHub implementation](https://
 For example, using `myst_heading_anchors = 2`:
 
 ::::{myst-example}
-## A heading with slug
+# A heading with slug
 
-## A heading with slug
+# A heading with slug
 
 <project:#a-heading-with-slug>
 

myst_parser/mdit_to_docutils/base.py

@@ -416,28 +416,35 @@ def copy_attributes(
                         continue
                 node[key] = value
 
-    def update_section_level_state(self, section: nodes.section, level: int) -> None:
+    def update_section_level_state(
+        self,
+        section: nodes.section,
+        level: int,
+        *,
+        parent: nodes.Element | None = None,
+    ) -> None:
         """Update the section level state, with the new current section and level."""
         # find the closest parent section
-        parent_level = max(
-            section_level
-            for section_level in self._level_to_section
-            if level > section_level
-        )
-        parent = self._level_to_section[parent_level]
-
-        # if we are jumping up to a non-consecutive level,
-        # then warn about this, since this will not be propagated in the docutils AST
-        if (level > parent_level) and (parent_level + 1 != level):
-            msg = f"Non-consecutive header level increase; H{parent_level} to H{level}"
-            if parent_level == 0:
-                msg = f"Document headings start at H{level}, not H1"
-            self.create_warning(
-                msg,
-                MystWarnings.MD_HEADING_NON_CONSECUTIVE,
-                line=section.line,
-                append_to=self.current_node,
+        if parent is None:
+            parent_level = max(
+                section_level
+                for section_level in self._level_to_section
+                if level > section_level
             )
+            parent = self._level_to_section[parent_level]
+
+            # if we are jumping up to a non-consecutive level,
+            # then warn about this, since this will not be propagated in the docutils AST
+            if (level > parent_level) and (parent_level + 1 != level):
+                msg = f"Non-consecutive header level increase; H{parent_level} to H{level}"
+                if parent_level == 0:
+                    msg = f"Document headings start at H{level}, not H1"
+                self.create_warning(
+                    msg,
+                    MystWarnings.MD_HEADING_NON_CONSECUTIVE,
+                    line=section.line,
+                    append_to=self.current_node,
+                )
 
         # append the new section to the parent
         parent.append(section)
@@ -818,8 +825,11 @@ def render_heading(self, token: SyntaxTreeNode) -> None:
             parent_of_temp_root
             or isinstance(self.current_node, nodes.document | nodes.section)
         ):
+            level_offset = max(self._level_to_section.keys())
+            level += level_offset
             # if this is not the case, we create a rubric node instead
             rubric = nodes.rubric(token.content, "", level=level)
+            rubric["heading-level"] = level
             self.add_line_and_source_path(rubric, token)
             self.copy_attributes(token, rubric, ("class", "id"))
             with self.current_node_context(rubric, append=True):
@@ -838,7 +848,11 @@ def render_heading(self, token: SyntaxTreeNode) -> None:
             new_section["classes"].extend(["tex2jax_ignore", "mathjax_ignore"])
 
         # update the state of the section levels
-        self.update_section_level_state(new_section, level)
+        self.update_section_level_state(
+            new_section,
+            level,
+            parent=self.current_node if parent_of_temp_root else None,
+        )
 
         # create the title for this section
         title_node = nodes.title(token.children[0].content if token.children else "")

tests/test_renderers/fixtures/docutil_syntax_elements.md

@@ -113,12 +113,19 @@ Heading Levels:
 
 Nested heading
 .
+# Main heading
 > # heading
+> ## sub-heading
 .
 <document source="notset">
-    <block_quote>
-        <rubric ids="heading" level="1" names="heading">
-            heading
+    <section ids="main-heading" names="main\ heading">
+        <title>
+            Main heading
+        <block_quote>
+            <rubric heading-level="2" ids="heading" level="2" names="heading">
+                heading
+            <rubric heading-level="3" ids="sub-heading" level="3" names="sub-heading">
+                sub-heading
 .
 
 Block Code:

tests/test_renderers/fixtures/sphinx_syntax_elements.md

@@ -113,12 +113,50 @@ Heading Levels:
 
 Nested heading
 .
+# Main heading
 > # heading
+> ## sub-heading
 .
 <document source="<src>/index.md">
-    <block_quote>
-        <rubric ids="heading" level="1" names="heading">
-            heading
+    <section ids="main-heading" names="main\ heading">
+        <title>
+            Main heading
+        <block_quote>
+            <rubric heading-level="2" ids="heading" level="2" names="heading">
+                heading
+            <rubric heading-level="3" ids="sub-heading" level="3" names="sub-heading">
+                sub-heading
+.
+
+Nested heading in object
+.
+```{object} foo
+bar
+# level 1
+wunderbar
+## level 2
+wunderbar
+```
+.
+<document source="<src>/index.md">
+    <index entries="">
+    <desc classes="object" desctype="object" domain="" no-contents-entry="False" no-index="False" no-index-entry="False" no-typesetting="False" nocontentsentry="False" noindex="False" noindexentry="False" objtype="object">
+        <desc_signature _toc_name="" _toc_parts="()" classes="sig sig-object">
+            <desc_name classes="sig-name descname" xml:space="preserve">
+                foo
+        <desc_content>
+            <paragraph>
+                bar
+            <section ids="level-1" names="level\ 1">
+                <title>
+                    level 1
+                <paragraph>
+                    wunderbar
+                <section ids="level-2" names="level\ 2">
+                    <title>
+                        level 2
+                    <paragraph>
+                        wunderbar
 .
 
 Block Code: