mir/bind
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-30 14:07:59 +00:00
Code Issues Releases Wiki Activity

Refactor and unite internal data structures for iscconf Sphinx extension

Browse Source 
It turns out it is easier to regenerate Sphinx-mandated structure in
get_objects than to maintain two separate data structures. I should have
realized that before.
This commit is contained in:
Petr Špaček 2022-05-12 09:20:46 +02:00
parent 475f7a9603
commit 2f2aa1d21c
1 changed files with 45 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -126,17 +126,29 @@ def domain_factory(domainname, domainlabel, todolist):
roles = {"ref": XRefRole(warn_dangling=True)} roles = {"ref": XRefRole(warn_dangling=True)}
initial_data = { initial_data = {
"statements": [], # object list for Sphinx API # name -> {"tags": [list of tags], ...}; see add_statement()
# our own metadata: name -> {"tags": [list of tags], "short": "short desc"} "statements": {},
"statements_extra": {},
} }
indices = {} # no custom indicies indices = {} # no custom indicies
def get_objects(self): def get_objects(self):
"""Sphinx API: iterable of object descriptions""" """
for obj in self.data["statements"]: Sphinx API:
yield obj Iterable of Sphinx object descriptions (tuples defined in the API).
"""
for obj in self.data["statements"].values():
yield tuple(
obj[key]
for key in [
"fullname",
"signature",
"label",
"docname",
"anchor",
"priority",
]
)
# pylint: disable=too-many-arguments # pylint: disable=too-many-arguments
def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
@ -175,18 +187,17 @@ def domain_factory(domainname, domainlabel, todolist):
name = "{}.{}.{}".format(domainname, "statement", signature) name = "{}.{}.{}".format(domainname, "statement", signature)
anchor = "{}-statement-{}".format(domainname, signature) anchor = "{}-statement-{}".format(domainname, signature)
self.data["statements_extra"][name] = {"tags": tags, "short": short} self.data["statements"][name] = {
# Sphinx API: name, dispname, type, docname, anchor, priority "tags": tags,
self.data["statements"].append( "short": short,
( # Sphinx API
name, "fullname": name, # internal name
signature, "signature": signature, # display name
domainlabel + " statement", "label": domainlabel + " statement", # description for index
self.env.docname, "docname": self.env.docname,
anchor, "anchor": anchor,
1, "priority": 1, # search priority
) }
)
def clear_doc(self, docname): def clear_doc(self, docname):
""" """
@ -194,13 +205,12 @@ def domain_factory(domainname, domainlabel, todolist):
Remove traces of a document in the domain-specific inventories. Remove traces of a document in the domain-specific inventories.
""" """
# use name->doc mapping from Sphinx metadata self.data["statements"] = dict(
for name, _, _, cur_docname, _, _ in self.data["statements"]: {
if cur_docname == docname: key: obj
if name in self.data["statements_extra"]: for key, obj in self.data["statements"].items()
del self.data["statements_extra"][name] if obj["docname"] != docname
self.data["statements"] = list( }
obj for obj in self.data["statements"] if obj[3] != docname
) )
def merge_domaindata(self, docnames, otherdata): def merge_domaindata(self, docnames, otherdata):
@ -214,10 +224,7 @@ def domain_factory(domainname, domainlabel, todolist):
that all existing domains in Sphinx distribution have todo like that all existing domains in Sphinx distribution have todo like
"deal with duplicates" but do nothing about them, so we just follow "deal with duplicates" but do nothing about them, so we just follow
the suite.""" the suite."""
self.data["statements"] = list( self.data["statements"].update(otherdata["statements"])
set(self.data["statements"] + otherdata["statements"])
)
self.data["statements_extra"].update(otherdata["statements_extra"])
@classmethod @classmethod
def process_statementlist_nodes(cls, app, doctree, fromdocname): def process_statementlist_nodes(cls, app, doctree, fromdocname):
@ -232,7 +239,7 @@ def domain_factory(domainname, domainlabel, todolist):
table_header = [ table_header = [
TableColumn("ref", "Statement name"), TableColumn("ref", "Statement name"),
TableColumn("short", "Short desc"), TableColumn("short", "Short desc"),
TableColumn("tags", "Tags"), TableColumn("tags_txt", "Tags"),
] ]
table_b = DictToDocutilsTableBuilder(table_header) table_b = DictToDocutilsTableBuilder(table_header)
table_b.append_iterable(iscconf.list_all(fromdocname)) table_b.append_iterable(iscconf.list_all(fromdocname))
@ -241,11 +248,8 @@ def domain_factory(domainname, domainlabel, todolist):
node.replace_self(table) node.replace_self(table)
def list_all(self, fromdocname): def list_all(self, fromdocname):
for statement in self.data["statements"]: for statement in self.data["statements"].values():
name, sig, _const, _doc, _anchor, _prio = statement tags_txt = ", ".join(statement["tags"])
extra = self.data["statements_extra"][name]
short = extra["short"]
tags = ", ".join(extra["tags"])
refpara = nodes.inline() refpara = nodes.inline()
refpara += self.resolve_xref( refpara += self.resolve_xref(
@ -253,17 +257,15 @@ def domain_factory(domainname, domainlabel, todolist):
fromdocname, fromdocname,
self.env.app.builder, self.env.app.builder,
None, None,
sig, statement["signature"],
None, None,
nodes.Text(sig), nodes.Text(statement["signature"]),
) )
yield { copy = statement.copy()
"fullname": name, copy["ref"] = refpara
"ref": refpara, copy["tags_txt"] = tags_txt
"short": short, yield copy
"tags": tags,
}
return ISCConfDomain return ISCConfDomain