Merge pull request #13993 from teto/gendoc

improve vimdoc generation

contrib/flake.nix

@@ -42,12 +42,16 @@
             disallowedReferences = [];
           }));
 
-          # for neovim developers, very slow
+          # for neovim developers, builds a slow binary
+          # huge closure size but aims at covering all scripts
           # brings development tools as well
           neovim-developer =
             let
               lib = nixpkgs.lib;
-              pythonEnv = pkgs.python3;
+              pythonEnv = pkgs.python3.withPackages(ps: [
+                ps.msgpack
+                ps.flake8  # for 'make pylint'
+              ]);
               luacheck = pkgs.luaPackages.luacheck;
             in
             (neovim-debug.override ({ doCheck = pkgs.stdenv.isLinux; })).overrideAttrs (oa: {
@@ -56,7 +60,7 @@
                 "-DMIN_LOG_LEVEL=0"
                 "-DENABLE_LTO=OFF"
                 "-DUSE_BUNDLED=OFF"
-              ] ++ pkgs.stdenv.lib.optionals pkgs.stdenv.isLinux [
+              ] ++ pkgs.lib.optionals pkgs.stdenv.isLinux [
                 # https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
                 # https://clang.llvm.org/docs/AddressSanitizer.html#symbolizing-the-reports
                 "-DCLANG_ASAN_UBSAN=ON"
@@ -66,7 +70,8 @@
                 pythonEnv
                 include-what-you-use # for scripts/check-includes.py
                 jq # jq for scripts/vim-patch.sh -r
-                doxygen
+                shellcheck # for `make shlint`
+                doxygen    # for script/gen_vimdoc.py
               ]);
 
               shellHook = oa.shellHook + ''
@@ -102,6 +107,5 @@
         defaultApp = apps.nvim;
 
         devShell = pkgs.neovim-developer;
-      }
-    );
+    });
 }

runtime/lua/vim/lsp/handlers.lua

@@ -26,7 +26,7 @@ end
 
 -- @msg of type ProgressParams
 -- Basically a token of type number/string
-local function progress_callback(_, _, params, client_id)
+local function progress_handler(_, _, params, client_id)
   local client = vim.lsp.get_client_by_id(client_id)
   local client_name = client and client.name or string.format("id=%d", client_id)
   if not client then
@@ -62,7 +62,7 @@ local function progress_callback(_, _, params, client_id)
 end
 
 --@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#progress
-M['$/progress'] = progress_callback
+M['$/progress'] = progress_handler
 
 --@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#window_workDoneProgress_create
 M['window/workDoneProgress/create'] =  function(_, _, params, client_id)

scripts/gen_vimdoc.py

@@ -48,6 +48,7 @@ import textwrap
 import subprocess
 import collections
 import msgpack
+import logging
 
 from xml.dom import minidom
 
@@ -57,10 +58,18 @@ if sys.version_info < MIN_PYTHON_VERSION:
     print("requires Python {}.{}+".format(*MIN_PYTHON_VERSION))
     sys.exit(1)
 
-DEBUG = ('DEBUG' in os.environ)
+# DEBUG = ('DEBUG' in os.environ)
 INCLUDE_C_DECL = ('INCLUDE_C_DECL' in os.environ)
 INCLUDE_DEPRECATED = ('INCLUDE_DEPRECATED' in os.environ)
 
+log = logging.getLogger(__name__)
+
+LOG_LEVELS = {
+    logging.getLevelName(level): level for level in [
+        logging.DEBUG, logging.INFO, logging.ERROR
+    ]
+}
+
 fmt_vimhelp = False  # HACK
 text_width = 78
 script_path = os.path.abspath(__file__)
@@ -157,7 +166,7 @@ CONFIG = {
         ]),
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
-        'section_name': {},
+        'section_name': {'lsp.lua': 'lsp'},
         'section_fmt': lambda name: (
             'Lua module: vim.lsp'
             if name.lower() == 'lsp'
@@ -726,8 +735,8 @@ def extract_from_xml(filename, target, width):
         if desc:
             for child in desc.childNodes:
                 paras.append(para_as_map(child))
-            if DEBUG:
-                print(textwrap.indent(
+            log.debug(
+                textwrap.indent(
                     re.sub(r'\n\s*\n+', '\n',
                            desc.toprettyxml(indent='  ', newl='\n')), ' ' * 16))
 
@@ -885,12 +894,13 @@ def main(config, args):
             os.remove(mpack_file)
 
         output_dir = out_dir.format(target=target)
+        debug = args.log_level >= logging.DEBUG
         p = subprocess.Popen(
                 ['doxygen', '-'],
                 stdin=subprocess.PIPE,
                 # silence warnings
                 # runtime/lua/vim/lsp.lua:209: warning: argument 'foo' not found
-                stderr=(subprocess.STDOUT if DEBUG else subprocess.DEVNULL))
+                stderr=(subprocess.STDOUT if debug else subprocess.DEVNULL))
         p.communicate(
             config.format(
                 input=CONFIG[target]['files'],
@@ -1039,6 +1049,10 @@ def filter_source(filename):
 def parse_args():
     targets = ', '.join(CONFIG.keys())
     ap = argparse.ArgumentParser()
+    ap.add_argument(
+        "--log-level", "-l", choices=LOG_LEVELS.keys(),
+        default=logging.getLevelName(logging.ERROR), help="Set log verbosity"
+    )
     ap.add_argument('source_filter', nargs='*',
                     help="Filter source file(s)")
     ap.add_argument('-k', '--keep-tmpfiles', action='store_true',
@@ -1085,6 +1099,10 @@ Doxyfile = textwrap.dedent('''
 
 if __name__ == "__main__":
     args = parse_args()
+    print("Setting log level to %s" % args.log_level)
+    args.log_level = LOG_LEVELS[args.log_level]
+    log.setLevel(args.log_level)
+
     if len(args.source_filter) > 0:
         filter_source(args.source_filter[0])
     else:

scripts/lua2dox_filter

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 ###########################################################################
 #   Copyright (C) 2012 by Simon Dales   #