🐛 support headings in nested parse

This fixes using Markdown headings in Sphinx objects,
like the `object`, `describe`, `py:data` directives, etc.

This works by adding the heading to the temp root parent
instead of at the end of the previous section from the main document.

Fixes #1050

Author: minijackson

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)
@@ -838,7 +845,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/sphinx_syntax_elements.md

@@ -121,6 +121,37 @@ Nested heading
             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:
 .
     foo