Parse and render rst syntax in :short: statement descriptions in tables

Without this change tables generated by .. namedconf:statementlist::
contained raw text and displayed rst syntax to users.

The raw docutil node returned by rst parser can contain unresolved
references (pending_xref nodes). We just store those nodes and let
Sphinx to resolve them later on.

Beware: This would not work if we injected nodes in later stages of
processing. All unresolved references must be in place before
'doctree-resolved' event is emitted (i.e. before resolve_references() is
called inside Sphinx).

diff --git a/doc/arm/_ext/iscconf.py b/doc/arm/_ext/iscconf.py
index ebbfa28fe4fca3f6514300778bac45821bbede51..598fb26aa3a2cb49c0f83f8ae1b5cef2e4260150 100644 (file)
--- a/doc/arm/_ext/iscconf.py
+++ b/doc/arm/_ext/iscconf.py
@@ -122,7 +122,9 @@ def domain_factory(domainname, domainlabel, todolist, grammar):
                 signode["ids"].append(domainname + "-statement-" + sig)
 
                 iscconf = self.env.get_domain(domainname)
-                iscconf.add_statement(sig, self.isc_tags, self.isc_short, self.lineno)
+                iscconf.add_statement(
+                    sig, self.isc_tags, self.isc_short, self.isc_short_node, self.lineno
+                )
 
             @property
             def isc_tags(self):
@@ -132,6 +134,11 @@ def domain_factory(domainname, domainlabel, todolist, grammar):
             def isc_short(self):
                 return self.options.get("short", "")
 
+            @property
+            def isc_short_node(self):
+                """Short description parsed from rst to docutils node"""
+                return self.parse_nested_str(self.isc_short)
+
             def format_path(self, path):
                 assert path[0] == "_top"
                 if len(path) == 1:
@@ -223,8 +230,7 @@ def domain_factory(domainname, domainlabel, todolist, grammar):
             def transform_content(self, contentnode: addnodes.desc_content) -> None:
                 """autogenerate content from structured data"""
                 if self.isc_short:
-                    short_parsed = self.parse_nested_str(self.isc_short)
-                    contentnode.insert(0, short_parsed)
+                    contentnode.insert(0, self.isc_short_node)
                 if self.isc_tags:
                     tags = nodes.paragraph()
                     tags += nodes.strong(text="Tags: ")
@@ -341,7 +347,7 @@ def domain_factory(domainname, domainlabel, todolist, grammar):
         def get_statement_name(self, signature):
             return "{}.{}.{}".format(domainname, "statement", signature)
 
-        def add_statement(self, signature, tags, short, lineno):
+        def add_statement(self, signature, tags, short, short_node, lineno):
             """
             Add a new statement to the domain data structures.
             No visible effect.
@@ -352,6 +358,7 @@ def domain_factory(domainname, domainlabel, todolist, grammar):
             new = {
                 "tags": tags,
                 "short": short,
+                "short_node": short_node,
                 "filename": self.env.doc2path(self.env.docname),
                 "lineno": lineno,
                 # Sphinx API
@@ -439,7 +446,7 @@ def domain_factory(domainname, domainlabel, todolist, grammar):
             def gen_replacement_table(acceptable_blocks, acceptable_tags):
                 table_header = [
                     TableColumn("ref", "Statement"),
-                    TableColumn("short", "Description"),
+                    TableColumn("short_node", "Description"),
                 ]
                 tag_header = []
                 if len(acceptable_tags) != 1:
@@ -556,6 +563,8 @@ class DictToDocutilsTableBuilder:
                 value = obj[column.dictkey]
                 if isinstance(value, str):
                     value = nodes.Text(value)
+                else:
+                    value = value.deepcopy()
                 entry += value
                 row += entry
             self.tbody.append(row)