ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity

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

Browse Source 
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).

(cherry picked from commit 62f3cf98d3)
This commit is contained in:
Petr Špaček
2022-07-04 12:33:04 +02:00
parent 6ac047cfaa
commit 96691c5873
1 changed files with 14 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
doc/arm/_ext/iscconf.py
View File

@@ -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)