gh-140014: Wrap C API annotations in a paragraph.

[encukou]

It turns out putting <emphasis> directly in <desc_content> is not valid docutils. Sphinx doesn't detect this, though.

@m-aciek, are you able to test this with rinohtype?

• Issue: Docs: C annotations extension produces invalid docutils tree #140014

---

📚 Documentation preview 📚: https://cpython-previews--145838.org.readthedocs.build/

[m-aciek]

The test is successful, as far as I'm concerned, as we are hitting a different (and unrelated) error. 🎉

• Run on your branch: https://github.com/m-aciek/python-docs-offline/actions/runs/22989740798/job/66747936682.
• Run on main: https://github.com/m-aciek/python-docs-offline/actions/runs/22989942678/job/66748549624.

[encukou]

I ran out of time I can give to it this week. Some notes in case you want to continue:

A hacky little patch for rinohtype that attaches some info about where we are to the `AttributeError`:

--- venv2/lib/python3.14/site-packages/rinoh/frontend/__init__.py       2026-03-12 08:30:20.079451917 +0000
+++ venv/lib/python3.14/site-packages/rinoh/frontend/__init__.py        2026-03-12 08:12:31.357154512 +0000
@@ -59,7 +59,13 @@
         for child in self.getchildren():
             if child.tag_name == name:
                 return child
-        raise AttributeError('No such element: {} in {}'.format(name, self))
+        error = AttributeError('No such element: {} in {}'.format(name, self))
+        node = self
+        error.add_note(f'! cannot get node/attribute {name!r}:')
+        while node:
+            error.add_note(f'  - {node} @ {node.node.source}:{node.node.line}: {repr(node.node.astext())[:20]}')
+            node = node.parent
+        raise error
 
     def __iter__(self):
         try:

Draft of the kind of things that need changing:

diff --git a/Doc/tools/extensions/audit_events.py b/Doc/tools/extensions/audit_events.py
index 385a58b2145..f38fa93960c 100644
--- a/Doc/tools/extensions/audit_events.py
+++ b/Doc/tools/extensions/audit_events.py
@@ -146,7 +146,7 @@ def run(self) -> list[nodes.paragraph]:
             ids.append(target)
         self.env.audit_events.add_event(name, args, (self.env.docname, target))
 
-        node = nodes.paragraph("", classes=["audit-hook"], ids=ids)
+        node = nodes.container("", classes=["audit-hook"], ids=ids)
         self.set_source_info(node)
         if self.content:
             node.rawsource = '\n'.join(self.content)  # for gettext
diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py
index 95649eae273..987c52b3002 100644
--- a/Doc/tools/extensions/c_annotations.py
+++ b/Doc/tools/extensions/c_annotations.py
@@ -242,7 +242,7 @@ def _unstable_api_annotation() -> nodes.admonition:
         reftype="ref",
         refexplicit="False",
     )
-    emph_node = nodes.emphasis(
+    return nodes.emphasis(
         "This is ",
         sphinx_gettext("This is") + " ",
         ref_node,
@@ -251,10 +251,6 @@ def _unstable_api_annotation() -> nodes.admonition:
                 ". It may change without warning in minor releases."
             )
         ),
-    )
-    return nodes.admonition(
-        "",
-        emph_node,
         classes=["unstable-c-api", "warning"],
     )
 
@@ -285,7 +281,7 @@ def run(self) -> list[nodes.Node]:
             f"* :c:{record.role}:`{record.name}`"
             for record in state["stable_abi_data"].values()
         ]
-        node = nodes.paragraph()
+        node = nodes.container()
         self.state.nested_parse(StringList(content), 0, node)
         return [node]