gh-101845: pyspecific: Fix i18n for availability directive (GH-101846)

pyspecific: Fix i18n for availability directive

If the directive has content, the previous code would nest paragraph
nodes from that content inside a general paragraph node, which confuses
Sphinx and leads it to drop the content when translating. Instead, use a
container node for the body.

Also use set_source_info so that any warnings have location info.
(cherry picked from commit 6ef6915)

Co-authored-by: Jean Abou-Samra <[email protected]>

Doc/tools/extensions/pyspecific.py

@@ -28,6 +28,7 @@
     from sphinx.environment import NoUri
 from sphinx.locale import _ as sphinx_gettext
 from sphinx.util import status_iterator, logging
+from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import split_explicit_title
 from sphinx.writers.text import TextWriter, TextTranslator
 from sphinx.writers.latex import LaTeXTranslator
@@ -124,7 +125,7 @@ def run(self):
 
 # Support for documenting platform availability
 
-class Availability(Directive):
+class Availability(SphinxDirective):
 
     has_content = True
     required_arguments = 1
@@ -144,18 +145,19 @@ class Availability(Directive):
 
     def run(self):
         availability_ref = ':ref:`Availability <availability>`: '
+        avail_nodes, avail_msgs = self.state.inline_text(
+            availability_ref + self.arguments[0],
+            self.lineno)
         pnode = nodes.paragraph(availability_ref + self.arguments[0],
-                                classes=["availability"],)
-        n, m = self.state.inline_text(availability_ref, self.lineno)
-        pnode.extend(n + m)
-        n, m = self.state.inline_text(self.arguments[0], self.lineno)
-        pnode.extend(n + m)
+                                '', *avail_nodes, *avail_msgs)
+        self.set_source_info(pnode)
+        cnode = nodes.container("", pnode, classes=["availability"])
+        self.set_source_info(cnode)
         if self.content:
-            self.state.nested_parse(self.content, self.content_offset, pnode)
-
+            self.state.nested_parse(self.content, self.content_offset, cnode)
         self.parse_platforms()
 
-        return [pnode]
+        return [cnode]
 
     def parse_platforms(self):
         """Parse platform information from arguments