From 46bde66147ead1bb234932a48e2c56fc4b698ec0 Mon Sep 17 00:00:00 2001 From: smolck <46855713+smolck@users.noreply.github.com> Date: Sat, 26 Oct 2019 14:54:54 -0500 Subject: gen_vimdoc.py: dump API docs to msgpack #11296 Convenient for API clients who want to reuse the API docs in their own docs. Could be used e.g. to eliminate nvim.net's own doxygen parser: https://github.com/neovim/nvim.net/tree/3a736232a4e7b7a2a1eff4bded24d2bf27a918c2/src/NvimClient.APIGenerator/Docs TODO: currently the result values are formatted as Vim help docs. We should change the values to have structure, something like this: [{ 'nvim_win_get_var': [ 'line1, 'line2', [ 'item1', 'item2', ... ] ], 'nvim_win_set_var': [ ... ], ... }] close #11296 --- scripts/gen_vimdoc.py | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) (limited to 'scripts/gen_vimdoc.py') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 373a58d11e..aa50132d4c 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -36,11 +36,12 @@ import shutil import textwrap import subprocess import collections +import msgpack from xml.dom import minidom -if sys.version_info[0] < 3: - print("use Python 3") +if sys.version_info[0] < 3 or sys.version_info[1] < 5: + print("requires Python 3.5+") sys.exit(1) DEBUG = ('DEBUG' in os.environ) @@ -453,7 +454,7 @@ def parse_source_xml(filename, mode): """ global xrefs xrefs = set() - functions = [] + functions = {} # Map of func_name:docstring. deprecated_functions = [] dom = minidom.parse(filename) @@ -577,11 +578,11 @@ def parse_source_xml(filename, mode): if 'Deprecated' in xrefs: deprecated_functions.append(func_doc) elif name.startswith(CONFIG[mode]['func_name_prefix']): - functions.append(func_doc) + functions[name] = func_doc xrefs.clear() - return '\n\n'.join(functions), '\n\n'.join(deprecated_functions) + return '\n\n'.join(list(functions.values())), '\n\n'.join(deprecated_functions), functions def delete_lines_below(filename, tokenstr): @@ -604,6 +605,12 @@ def gen_docs(config): Doxygen is called and configured through stdin. """ for mode in CONFIG: + functions = {} # Map of func_name:docstring. + mpack_file = os.path.join(base_dir, 'runtime', 'doc', + CONFIG[mode]['filename'].replace('.txt', '.mpack')) + if os.path.exists(mpack_file): + os.remove(mpack_file) + output_dir = out_dir.format(mode=mode) p = subprocess.Popen(['doxygen', '-'], stdin=subprocess.PIPE) p.communicate( @@ -645,14 +652,15 @@ def gen_docs(config): filename = get_text(find_first(compound, 'name')) if filename.endswith('.c') or filename.endswith('.lua'): - functions, deprecated = parse_source_xml( + functions_text, deprecated_text, fns = parse_source_xml( os.path.join(base, '%s.xml' % compound.getAttribute('refid')), mode) + # Collect functions from all modules (for the current `mode`). + functions = {**functions, **fns} - if not functions and not deprecated: + if not functions_text and not deprecated_text: continue - - if functions or deprecated: + else: name = os.path.splitext(os.path.basename(filename))[0] if name == 'ui': name = name.upper() @@ -665,12 +673,12 @@ def gen_docs(config): if intro: doc += '\n\n' + intro - if functions: - doc += '\n\n' + functions + if functions_text: + doc += '\n\n' + functions_text - if INCLUDE_DEPRECATED and deprecated: + if INCLUDE_DEPRECATED and deprecated_text: doc += '\n\n\nDeprecated %s Functions: ~\n\n' % name - doc += deprecated + doc += deprecated_text if doc: filename = os.path.basename(filename) @@ -713,6 +721,8 @@ def gen_docs(config): delete_lines_below(doc_file, CONFIG[mode]['section_start_token']) with open(doc_file, 'ab') as fp: fp.write(docs.encode('utf8')) + with open(mpack_file, 'wb') as fp: + fp.write(msgpack.packb(functions, use_bin_type=True)) shutil.rmtree(output_dir) -- cgit From 6d8fe9b3f40d0d3f4ddeed56f592dfd2be810f7f Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 26 Oct 2019 16:21:22 -0700 Subject: lint --- scripts/gen_vimdoc.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'scripts/gen_vimdoc.py') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index aa50132d4c..8d0cf54828 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -582,7 +582,9 @@ def parse_source_xml(filename, mode): xrefs.clear() - return '\n\n'.join(list(functions.values())), '\n\n'.join(deprecated_functions), functions + return ('\n\n'.join(list(functions.values())), + '\n\n'.join(deprecated_functions), + functions) def delete_lines_below(filename, tokenstr): @@ -606,7 +608,8 @@ def gen_docs(config): """ for mode in CONFIG: functions = {} # Map of func_name:docstring. - mpack_file = os.path.join(base_dir, 'runtime', 'doc', + mpack_file = os.path.join( + base_dir, 'runtime', 'doc', CONFIG[mode]['filename'].replace('.txt', '.mpack')) if os.path.exists(mpack_file): os.remove(mpack_file) @@ -653,8 +656,8 @@ def gen_docs(config): filename = get_text(find_first(compound, 'name')) if filename.endswith('.c') or filename.endswith('.lua'): functions_text, deprecated_text, fns = parse_source_xml( - os.path.join(base, '%s.xml' % - compound.getAttribute('refid')), mode) + os.path.join(base, '{}.xml'.format( + compound.getAttribute('refid'))), mode) # Collect functions from all modules (for the current `mode`). functions = {**functions, **fns} -- cgit From af53a0c0123338575dd59934449d7fe836835d1c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 17 Nov 2019 19:06:59 -0800 Subject: doc: Lua [ci skip] #11378 - Rework :help lua-commands - Rename if_lua.txt => lua.txt --- scripts/gen_vimdoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/gen_vimdoc.py') diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 8d0cf54828..4d71d5e15e 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -85,7 +85,7 @@ CONFIG = { 'append_only': [], }, 'lua': { - 'filename': 'if_lua.txt', + 'filename': 'lua.txt', 'section_start_token': '*lua-vim*', 'section_order': [ 'vim.lua', -- cgit