kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-24 13:15:09 -07:00
Code Issues Packages Projects Releases Wiki Activity

build(gen_vimdoc): eliminate non-constant global variables (#17781)

Browse Source
This commit is contained in:
dundargoc 2022-05-15 11:23:56 +02:00 committed by GitHub
parent 0a66c4a72a
commit b1b5802009
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
scripts/gen_vimdoc.py
View File

@ -79,13 +79,11 @@ LOG_LEVELS = {
]
}
fmt_vimhelp = False # HACK
text_width = 78
script_path = os.path.abspath(__file__)
base_dir = os.path.dirname(os.path.dirname(script_path))
out_dir = os.path.join(base_dir, 'tmp-{target}-doc')
filter_cmd = '%s %s' % (sys.executable, script_path)
seen_funcs = set()
msgs = [] # Messages to show on exit.
lua2dox_filter = os.path.join(base_dir, 'scripts', 'lua2dox_filter')
@ -287,11 +285,6 @@ annotation_map = {
}
# Tracks `xrefsect` titles. As of this writing, used only for separating
# deprecated functions.
xrefs = set()
# Raises an error with details about `o`, if `cond` is in object `o`,
# or if `cond()` is callable and returns True.
def debug_this(o, cond=True):
@ -485,10 +478,8 @@ def update_params_map(parent, ret_map, width=62):
return ret_map
def render_node(n, text, prefix='', indent='', width=62):
def render_node(n, text, prefix='', indent='', width=62, fmt_vimhelp=False):
"""Renders a node as Vim help text, recursively traversing all descendants."""
global fmt_vimhelp
global has_seen_preformatted
def ind(s):
return s if fmt_vimhelp else ''
@ -566,7 +557,7 @@ def render_node(n, text, prefix='', indent='', width=62):
return text
def para_as_map(parent, indent='', width=62):
def para_as_map(parent, indent='', width=62, fmt_vimhelp=False):
"""Extracts a Doxygen XML <para> node to a map.
Keys:
@ -599,7 +590,8 @@ def para_as_map(parent, indent='', width=62):
last = ''
if is_inline(parent):
# Flatten inline text from a tree of non-block nodes.
text = doc_wrap(render_node(parent, ""), indent=indent, width=width)
text = doc_wrap(render_node(parent, "", fmt_vimhelp=fmt_vimhelp),
indent=indent, width=width)
else:
prev = None # Previous node
for child in parent.childNodes:
@ -615,7 +607,8 @@ def para_as_map(parent, indent='', width=62):
elif kind == 'see':
groups['seealso'].append(child)
elif kind in ('note', 'warning'):
text += render_node(child, text, indent=indent, width=width)
text += render_node(child, text, indent=indent,
width=width, fmt_vimhelp=fmt_vimhelp)
else:
raise RuntimeError('unhandled simplesect: {}\n{}'.format(
child.nodeName, child.toprettyxml(indent=' ', newl='\n')))
@ -628,7 +621,8 @@ def para_as_map(parent, indent='', width=62):
and ' ' != text[-1]):
text += ' '
text += render_node(child, text, indent=indent, width=width)
text += render_node(child, text, indent=indent, width=width,
fmt_vimhelp=fmt_vimhelp)
prev = child
chunks['text'] += text
@ -639,10 +633,12 @@ def para_as_map(parent, indent='', width=62):
update_params_map(child, ret_map=chunks['params'], width=width)
for child in groups['return']:
chunks['return'].append(render_node(
child, '', indent=indent, width=width))
child, '', indent=indent, width=width, fmt_vimhelp=fmt_vimhelp))
for child in groups['seealso']:
chunks['seealso'].append(render_node(
child, '', indent=indent, width=width))
child, '', indent=indent, width=width, fmt_vimhelp=fmt_vimhelp))
xrefs = set()
for child in groups['xrefs']:
# XXX: Add a space (or any char) to `title` here, otherwise xrefs
# ("Deprecated" section) acts very weird...
@ -652,10 +648,10 @@ def para_as_map(parent, indent='', width=62):
chunks['xrefs'].append(doc_wrap(xrefdesc, prefix='{}: '.format(title),
width=width) + '\n')
return chunks
return chunks, xrefs
def fmt_node_as_vimhelp(parent, width=62, indent=''):
def fmt_node_as_vimhelp(parent, width=62, indent='', fmt_vimhelp=False):
"""Renders (nested) Doxygen <para> nodes as Vim :help text.
NB: Blank lines in a docstring manifest as <para> tags.
@ -678,7 +674,7 @@ def fmt_node_as_vimhelp(parent, width=62, indent=''):
return True
for child in parent.childNodes:
para = para_as_map(child, indent, width)
para, _ = para_as_map(child, indent, width, fmt_vimhelp)
# Generate text from the gathered items.
chunks = [para['text']]
@ -702,19 +698,16 @@ def fmt_node_as_vimhelp(parent, width=62, indent=''):
return clean_lines('\n'.join(rendered_blocks).strip())
def extract_from_xml(filename, target, width):
def extract_from_xml(filename, target, width, fmt_vimhelp):
"""Extracts Doxygen info as maps without formatting the text.
Returns two maps:
1. Functions
2. Deprecated functions
The `fmt_vimhelp` global controls some special cases for use by
The `fmt_vimhelp` variable controls some special cases for use by
fmt_doxygen_xml_as_vimhelp(). (TODO: ugly :)
"""
global xrefs
global fmt_vimhelp
xrefs.clear()
fns = {} # Map of func_name:docstring.
deprecated_fns = {} # Map of func_name:docstring.
@ -821,16 +814,22 @@ def extract_from_xml(filename, target, width):
signature = prefix + suffix
signature += vimtag.rjust(width - len(signature))
# Tracks `xrefsect` titles. As of this writing, used only for separating
# deprecated functions.
xrefs_all = set()
paras = []
brief_desc = find_first(member, 'briefdescription')
if brief_desc:
for child in brief_desc.childNodes:
paras.append(para_as_map(child))
para, xrefs = para_as_map(child)
xrefs_all.update(xrefs)
desc = find_first(member, 'detaileddescription')
if desc:
for child in desc.childNodes:
paras.append(para_as_map(child))
para, xrefs = para_as_map(child)
paras.append(para)
xrefs_all.update(xrefs)
log.debug(
textwrap.indent(
re.sub(r'\n\s*\n+', '\n',
@ -846,7 +845,6 @@ def extract_from_xml(filename, target, width):
'seealso': [],
}
if fmt_vimhelp:
# HACK :(
fn['desc_node'] = desc
fn['brief_desc_node'] = brief_desc
@ -865,18 +863,16 @@ def extract_from_xml(filename, target, width):
if INCLUDE_C_DECL:
fn['c_decl'] = c_decl
if 'Deprecated' in str(xrefs):
if 'Deprecated' in str(xrefs_all):
deprecated_fns[name] = fn
elif name.startswith(CONFIG[target]['fn_name_prefix']):
fns[name] = fn
xrefs.clear()
fns = collections.OrderedDict(sorted(
fns.items(),
key=lambda key_item_tuple: key_item_tuple[0].lower()))
deprecated_fns = collections.OrderedDict(sorted(deprecated_fns.items()))
return (fns, deprecated_fns)
return fns, deprecated_fns
def fmt_doxygen_xml_as_vimhelp(filename, target):
@ -886,16 +882,14 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
1. Vim help text for functions found in `filename`.
2. Vim help text for deprecated functions.
"""
global fmt_vimhelp
fmt_vimhelp = True
fns_txt = {} # Map of func_name:vim-help-text.
deprecated_fns_txt = {} # Map of func_name:vim-help-text.
fns, _ = extract_from_xml(filename, target, width=text_width)
fns, _ = extract_from_xml(filename, target, text_width, True)
for name, fn in fns.items():
# Generate Vim :help for parameters.
if fn['desc_node']:
doc = fmt_node_as_vimhelp(fn['desc_node'])
doc = fmt_node_as_vimhelp(fn['desc_node'], fmt_vimhelp=True)
if not doc and fn['brief_desc_node']:
doc = fmt_node_as_vimhelp(fn['brief_desc_node'])
if not doc:
@ -948,14 +942,9 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
func_doc = "\n".join(split_lines)
if 'Deprecated' in xrefs:
deprecated_fns_txt[name] = func_doc
elif name.startswith(CONFIG[target]['fn_name_prefix']):
if name.startswith(CONFIG[target]['fn_name_prefix']):
fns_txt[name] = func_doc
xrefs.clear()
fmt_vimhelp = False
return ('\n\n'.join(list(fns_txt.values())),
'\n\n'.join(list(deprecated_fns_txt.values())))
@ -1059,7 +1048,7 @@ def main(config, args):
xmlfile = os.path.join(base,
'{}.xml'.format(compound.getAttribute('refid')))
# Extract unformatted (*.mpack).
fn_map, _ = extract_from_xml(xmlfile, target, width=9999)
fn_map, _ = extract_from_xml(xmlfile, target, 9999, False)
# Extract formatted (:help).
functions_text, deprecated_text = fmt_doxygen_xml_as_vimhelp(
os.path.join(base, '{}.xml'.format(