Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit cb65781

Browse files
freddrakefreddrake
committed
Rewrite code that converts the little descriptor environments to build
the right <signature>s and <description>. This seems to work a lot better now!
1 parent 38a5a3b commit cb65781

1 file changed

Lines changed: 114 additions & 53 deletions

File tree

‎Doc/tools/sgmlconv/docfixer.py‎

Lines changed: 114 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -123,52 +123,124 @@ def cleanup_root_text(doc):
123123
doc.removeChild(node)
124124

125125

126-
def handle_args(doc):
127-
for node in find_all_elements(doc, "args"):
128-
parent = node.parentNode
129-
nodes = []
130-
for n in parent.childNodes:
131-
if n.nodeType != xml.dom.core.ELEMENT or n.tagName != "args":
132-
nodes.append(n)
133-
signature = doc.createElement("signature")
134-
signature.appendChild(doc.createTextNode("\n "))
135-
name = doc.createElement("name")
136-
name.appendChild(doc.createTextNode(parent.getAttribute("name")))
137-
parent.removeAttribute("name")
138-
signature.appendChild(name)
139-
desc = doc.createElement("description")
140-
for n in nodes:
141-
parent.removeChild(n)
142-
desc.appendChild(n)
143-
desc.appendChild(doc.createTextNode("\n "))
144-
parent.replaceChild(signature, node)
145-
parent.insertBefore(doc.createTextNode("\n "), signature)
146-
if node.childNodes:
147-
# keep the <args>...</args>, newline & indent
126+
DESCRIPTOR_ELEMENTS = (
127+
"cfuncdesc", "cvardesc", "ctypedesc",
128+
"classdesc", "memberdesc", "memberdescni", "methoddesc", "methoddescni",
129+
"excdesc", "funcdesc", "funcdescni", "opcodedesc",
130+
"datadesc", "datadescni",
131+
)
132+
133+
def fixup_descriptors(doc):
134+
for tagName in DESCRIPTOR_ELEMENTS:
135+
nodes = find_all_elements(doc, tagName)
136+
for node in nodes:
137+
rewrite_descriptor(doc, node)
138+
139+
def rewrite_descriptor(doc, descriptor):
140+
#
141+
# Do these things:
142+
# 1. Add an "index=noindex" attribute to the element if the tagName
143+
# ends in 'ni', removing the 'ni' from the name.
144+
# 2. Create a <signature> from the name attribute and <args>.
145+
# 3. Create additional <signature>s from <*line{,ni}> elements,
146+
# if found.
147+
# 4. Move remaining child nodes to a <description> element.
148+
# 5. Put it back together.
149+
#
150+
descname = descriptor.tagName
151+
index = 1
152+
if descname[-2:] == "ni":
153+
descname = descname[:-2]
154+
descriptor.setAttribute("index", "noindex")
155+
descriptor._node.name = descname
156+
index = 0
157+
desctype = descname[:-4] # remove 'desc'
158+
linename = desctype + "line"
159+
if not index:
160+
linename = linename + "ni"
161+
# 2.
162+
signature = doc.createElement("signature")
163+
name = doc.createElement("name")
164+
signature.appendChild(doc.createTextNode("\n "))
165+
signature.appendChild(name)
166+
name.appendChild(doc.createTextNode(descriptor.getAttribute("name")))
167+
descriptor.removeAttribute("name")
168+
if descriptor.attributes.has_key("var"):
169+
variable = descriptor.getAttribute("var")
170+
if variable:
171+
args = doc.createElement("args")
172+
args.appendChild(doc.createTextNode(variable))
148173
signature.appendChild(doc.createTextNode("\n "))
149-
signature.appendChild(node)
150-
parent.appendChild(doc.createText("\n "))
151-
parent.appendChild(desc)
152-
parent.appendChild(doc.createText("\n"))
153-
signature.appendChild(doc.createTextNode("\n "))
174+
signature.appendChild(args)
175+
descriptor.removeAttribute("var")
176+
newchildren = [signature]
177+
children = descriptor.childNodes
178+
pos = skip_leading_nodes(children, 0)
179+
if pos < len(children):
180+
child = children[pos]
181+
if child.nodeType == xml.dom.core.ELEMENT and child.tagName == "args":
182+
# create an <args> in <signature>:
183+
args = doc.createElement("args")
184+
argchildren = []
185+
map(argchildren.append, child.childNodes)
186+
for n in argchildren:
187+
child.removeChild(n)
188+
args.appendChild(n)
189+
signature.appendChild(doc.createTextNode("\n "))
190+
signature.appendChild(args)
191+
signature.appendChild(doc.createTextNode("\n "))
192+
# 3.
193+
pos = skip_leading_nodes(children, pos + 1)
194+
while pos < len(children) \
195+
and children[pos].nodeType == xml.dom.core.ELEMENT \
196+
and children[pos].tagName == linename:
197+
# this is really a supplemental signature, create <signature>
198+
sig = methodline_to_signature(doc, children[pos])
199+
newchildren.append(sig)
200+
pos = skip_leading_nodes(children, pos + 1)
201+
# 4.
202+
description = doc.createElement("description")
203+
description.appendChild(doc.createTextNode("\n"))
204+
newchildren.append(description)
205+
move_children(descriptor, description, pos)
206+
last = description.childNodes[-1]
207+
if last.nodeType == xml.dom.core.TEXT:
208+
last.data = string.rstrip(last.data) + "\n "
209+
# 5.
210+
# should have nothing but whitespace and signature lines in <descriptor>;
211+
# discard them
212+
while descriptor.childNodes:
213+
descriptor.removeChild(descriptor.childNodes[0])
214+
for node in newchildren:
215+
descriptor.appendChild(doc.createTextNode("\n "))
216+
descriptor.appendChild(node)
217+
descriptor.appendChild(doc.createTextNode("\n"))
154218

155219

156220
def methodline_to_signature(doc, methodline):
157221
signature = doc.createElement("signature")
158222
signature.appendChild(doc.createTextNode("\n "))
159223
name = doc.createElement("name")
160224
name.appendChild(doc.createTextNode(methodline.getAttribute("name")))
225+
methodline.removeAttribute("name")
161226
signature.appendChild(name)
162-
methodline.parentNode.removeChild(methodline)
163227
if len(methodline.childNodes):
164-
methodline._node.name = "args"
165-
methodline.removeAttribute("name")
228+
args = doc.createElement("args")
166229
signature.appendChild(doc.createTextNode("\n "))
167-
signature.appendChild(methodline)
230+
signature.appendChild(args)
231+
move_children(methodline, args)
168232
signature.appendChild(doc.createTextNode("\n "))
169233
return signature
170234

171235

236+
def move_children(origin, dest, start=0):
237+
children = origin.childNodes
238+
while start < len(children):
239+
node = children[start]
240+
origin.removeChild(node)
241+
dest.appendChild(node)
242+
243+
172244
def handle_appendix(doc):
173245
# must be called after simplfy() if document is multi-rooted to begin with
174246
docelem = doc.documentElement
@@ -468,25 +540,16 @@ def move_elements_by_name(doc, source, dest, name, sep=None):
468540
dest.appendChild(doc.createTextNode(sep))
469541

470542

471-
FIXUP_PARA_ELEMENTS = (
472-
"chapter",
473-
"section", "subsection", "subsubsection",
474-
"paragraph", "subparagraph",
475-
"excdesc", "datadesc",
476-
"excdescni", "datadescni",
477-
)
478-
479543
RECURSE_INTO_PARA_CONTAINERS = (
480-
"chapter",
544+
"chapter", "abstract", "enumerate",
481545
"section", "subsection", "subsubsection",
482546
"paragraph", "subparagraph",
483-
"abstract",
484-
"memberdesc", "memberdescni", "datadesc", "datadescni",
547+
"howto", "manual",
485548
)
486549

487550
PARA_LEVEL_ELEMENTS = (
488-
"moduleinfo", "title", "verbatim",
489-
"opcodedesc", "classdesc",
551+
"moduleinfo", "title", "verbatim", "enumerate", "item",
552+
"opcodedesc", "classdesc", "datadesc",
490553
"funcdesc", "methoddesc", "excdesc",
491554
"funcdescni", "methoddescni", "excdescni",
492555
"tableii", "tableiii", "tableiv", "localmoduletable",
@@ -496,10 +559,8 @@ def move_elements_by_name(doc, source, dest, name, sep=None):
496559
)
497560

498561
PARA_LEVEL_PRECEEDERS = (
499-
"index", "indexii", "indexiii", "indexiv",
500-
"stindex", "obindex", "COMMENT", "label", "input",
501-
"memberline", "memberlineni",
502-
"methodline", "methodlineni",
562+
"index", "indexii", "indexiii", "indexiv", "setindexsubitem",
563+
"stindex", "obindex", "COMMENT", "label", "input", "title",
503564
)
504565

505566

@@ -509,9 +570,9 @@ def fixup_paras(doc):
509570
and child.tagName in RECURSE_INTO_PARA_CONTAINERS:
510571
#
511572
fixup_paras_helper(doc, child)
512-
descriptions = child.getElementsByTagName("description")
513-
for description in descriptions:
514-
fixup_paras_helper(doc, description)
573+
descriptions = find_all_elements(doc, "description")
574+
for description in descriptions:
575+
fixup_paras_helper(doc, description)
515576

516577

517578
def fixup_paras_helper(doc, container, depth=0):
@@ -543,7 +604,7 @@ def build_para(doc, parent, start, i):
543604
children = parent.childNodes
544605
after = start + 1
545606
have_last = 0
546-
BREAK_ELEMENTS = PARA_LEVEL_ELEMENTS + FIXUP_PARA_ELEMENTS
607+
BREAK_ELEMENTS = PARA_LEVEL_ELEMENTS + RECURSE_INTO_PARA_CONTAINERS
547608
# Collect all children until \n\n+ is found in a text node or a
548609
# member of BREAK_ELEMENTS is found.
549610
for j in range(start, i):
@@ -707,7 +768,6 @@ def convert(ifp, ofp):
707768
p.feed(ifp.read())
708769
doc = p.document
709770
normalize(doc)
710-
handle_args(doc)
711771
simplify(doc)
712772
handle_labels(doc)
713773
handle_appendix(doc)
@@ -724,6 +784,7 @@ def convert(ifp, ofp):
724784
cleanup_root_text(doc)
725785
cleanup_trailing_parens(doc, ["function", "method", "cfunction"])
726786
cleanup_synopses(doc)
787+
fixup_descriptors(doc)
727788
normalize(doc)
728789
fixup_paras(doc)
729790
fixup_sectionauthors(doc)

0 commit comments

Comments
 (0)