Merge pull request #17707 from tesaguri/refactor-gen_vimdoc

runtime/doc/api.txt

@@ -594,7 +594,8 @@ nvim__id_float({flt})                                       *nvim__id_float()*
                     its argument.
 
 nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
-                TODO: Documentation
+                NB: if your UI doesn't use hlstate, this will not return
+                hlstate first time.
 
 nvim__runtime_inspect()                              *nvim__runtime_inspect()*
                 TODO: Documentation
@@ -1247,8 +1248,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
 nvim_list_bufs()                                            *nvim_list_bufs()*
                 Gets the current list of buffer handles
 
-                Includes unlisted (unloaded/deleted) buffers, like `:ls!` .
+                Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
-                Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
+                |nvim_buf_is_loaded()| to check if a buffer is loaded.
 
                 Return: ~
                     List of buffer handles
@@ -1547,18 +1548,21 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                 Sets a highlight group.
 
                 Parameters: ~
-                    {ns_id}  Namespace id for this highlight |nvim_create_namespace()|.
+                    {ns_id}  Namespace id for this highlight
-                             Use 0 to set a highlight group globally |:highlight|.
+                             |nvim_create_namespace()|. Use 0 to set a
+                             highlight group globally |:highlight|.
                     {name}   Highlight group name, e.g. "ErrorMsg"
                     {val}    Highlight definition map, like |synIDattr()|. In
                              addition, the following keys are recognized:
-                             • default: Don't override existing definition |:hi-default|
+                             • default: Don't override existing definition
-                             • ctermfg: Sets foreground of cterm color |highlight-ctermfg|
+                               |:hi-default|
-                             • ctermbg: Sets background of cterm color |highlight-ctermbg|
+                             • ctermfg: Sets foreground of cterm color
+                               |highlight-ctermfg|
+                             • ctermbg: Sets background of cterm color
+                               |highlight-ctermbg|
                              • cterm: cterm attribute map, like
-                               |highlight-args|.
+                               |highlight-args|. Note: Attributes default to
-                               Note: Attributes default to those set for `gui`
+                               those set for `gui` if not set.
-                                     if not set.
 
 nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                 Sets a global |mapping| for the given mode.
@@ -1879,8 +1883,9 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                     {buffer}       Buffer handle, or 0 for current buffer
                     {send_buffer}  True if the initial notification should
                                    contain the whole buffer: first
-                                   notification will be `nvim_buf_lines_event`
+                                   notification will be
-                                   . Else the first notification will be
+                                   `nvim_buf_lines_event`. Else the first
+                                   notification will be
                                    `nvim_buf_changedtick_event`. Not for Lua
                                    callbacks.
                     {opts}         Optional parameters.

runtime/doc/lsp.txt

@@ -800,8 +800,8 @@ start_client({config})                                *vim.lsp.start_client()*
                                          its result.
                                          • Note: To send an empty dictionary
                                            use
-                                           `{[vim.type_idx]=vim.types.dictionary}`
+                                           `{[vim.type_idx]=vim.types.dictionary}`,
-                                           , else it will be encoded as an
+                                           else it will be encoded as an
                                            array.
                     {handlers}           Map of language server method names
                                          to |lsp-handler|

runtime/doc/lua.txt

@@ -1990,9 +1990,9 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                     vim.keymap.set('n', 'asdf', require('jkl').my_fun)
 <
 
-                the require('jkl') gets evaluated during this call in order to
+                the require('jkl )` gets evaluated during this call in order to access the
-                access the function. If you want to avoid this cost at startup
+                function. If you want to avoid this cost at startup you can
-                you can wrap it in a function, for example: >
+                wrap it in a function, for example: >
 
                     vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 <

runtime/doc/treesitter.txt

@@ -528,8 +528,8 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
                 a table mapping capture indices to nodes, and metadata from
                 any directives processing the match. If the query has more
                 than one pattern the capture table might be sparse, and e.g.
-                `pairs()` method should be used over `ipairs` . Here an
+                `pairs()` method should be used over `ipairs`. Here an example
-                example iterating over all captures in every match:
+                iterating over all captures in every match:
 >
 
     for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do

scripts/gen_vimdoc.py

@@ -84,8 +84,6 @@ CONFIG = {
     'api': {
         'mode': 'c',
         'filename': 'api.txt',
-        # String used to find the start of the generated part of the doc.
-        'section_start_token': '*api-global*',
         # Section ordering.
         'section_order': [
             'vim.c',
@@ -98,8 +96,8 @@ CONFIG = {
             'autocmd.c',
             'ui.c',
         ],
-        # List of files/directories for doxygen to read, separated by blanks
+        # List of files/directories for doxygen to read, relative to `base_dir`
-        'files': os.path.join(base_dir, 'src/nvim/api'),
+        'files': ['src/nvim/api'],
         # file patterns used by doxygen
         'file_patterns': '*.h *.c',
         # Only function with this prefix are considered
@@ -122,7 +120,6 @@ CONFIG = {
     'lua': {
         'mode': 'lua',
         'filename': 'lua.txt',
-        'section_start_token': '*lua-vim*',
         'section_order': [
             '_editor.lua',
             'shared.lua',
@@ -131,14 +128,14 @@ CONFIG = {
             'filetype.lua',
             'keymap.lua',
         ],
-        'files': ' '.join([
+        'files': [
-            os.path.join(base_dir, 'runtime/lua/vim/_editor.lua'),
+            'runtime/lua/vim/_editor.lua',
-            os.path.join(base_dir, 'runtime/lua/vim/shared.lua'),
+            'runtime/lua/vim/shared.lua',
-            os.path.join(base_dir, 'runtime/lua/vim/uri.lua'),
+            'runtime/lua/vim/uri.lua',
-            os.path.join(base_dir, 'runtime/lua/vim/ui.lua'),
+            'runtime/lua/vim/ui.lua',
-            os.path.join(base_dir, 'runtime/lua/vim/filetype.lua'),
+            'runtime/lua/vim/filetype.lua',
-            os.path.join(base_dir, 'runtime/lua/vim/keymap.lua'),
+            'runtime/lua/vim/keymap.lua',
-        ]),
+        ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {
@@ -171,7 +168,6 @@ CONFIG = {
     'lsp': {
         'mode': 'lua',
         'filename': 'lsp.txt',
-        'section_start_token': '*lsp-core*',
         'section_order': [
             'lsp.lua',
             'buf.lua',
@@ -185,10 +181,10 @@ CONFIG = {
             'sync.lua',
             'protocol.lua',
         ],
-        'files': ' '.join([
+        'files': [
-            os.path.join(base_dir, 'runtime/lua/vim/lsp'),
+            'runtime/lua/vim/lsp',
-            os.path.join(base_dir, 'runtime/lua/vim/lsp.lua'),
+            'runtime/lua/vim/lsp.lua',
-        ]),
+        ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {'lsp.lua': 'lsp'},
@@ -214,11 +210,10 @@ CONFIG = {
     'diagnostic': {
         'mode': 'lua',
         'filename': 'diagnostic.txt',
-        'section_start_token': '*diagnostic-api*',
         'section_order': [
             'diagnostic.lua',
         ],
-        'files': os.path.join(base_dir, 'runtime/lua/vim/diagnostic.lua'),
+        'files': ['runtime/lua/vim/diagnostic.lua'],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {'diagnostic.lua': 'diagnostic'},
@@ -231,7 +226,6 @@ CONFIG = {
     'treesitter': {
         'mode': 'lua',
         'filename': 'treesitter.txt',
-        'section_start_token': '*lua-treesitter-core*',
         'section_order': [
             'treesitter.lua',
             'language.lua',
@@ -239,10 +233,10 @@ CONFIG = {
             'highlighter.lua',
             'languagetree.lua',
         ],
-        'files': ' '.join([
+        'files': [
-            os.path.join(base_dir, 'runtime/lua/vim/treesitter.lua'),
+            'runtime/lua/vim/treesitter.lua',
-            os.path.join(base_dir, 'runtime/lua/vim/treesitter/'),
+            'runtime/lua/vim/treesitter/',
-        ]),
+        ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {},
@@ -349,14 +343,6 @@ def self_or_child(n):
     return n.childNodes[0]
 
 
-def clean_text(text):
-    """Cleans text.
-
-    Only cleans superfluous whitespace at the moment.
-    """
-    return ' '.join(text.split()).strip()
-
-
 def clean_lines(text):
     """Removes superfluous lines.
 
@@ -380,9 +366,9 @@ def get_text(n, preformatted=False):
         return '`{}`'.format(text)
     for node in n.childNodes:
         if node.nodeType == node.TEXT_NODE:
-            text += node.data if preformatted else clean_text(node.data)
+            text += node.data
         elif node.nodeType == node.ELEMENT_NODE:
-            text += ' ' + get_text(node, preformatted)
+            text += get_text(node, preformatted)
     return text
 
 
@@ -849,7 +835,9 @@ def extract_from_xml(filename, target, width):
             'seealso': [],
         }
         if fmt_vimhelp:
-            fn['desc_node'] = desc  # HACK :(
+            # HACK :(
+            fn['desc_node'] = desc
+            fn['brief_desc_node'] = brief_desc
 
         for m in paras:
             if 'text' in m:
@@ -897,6 +885,8 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
         # Generate Vim :help for parameters.
         if fn['desc_node']:
             doc = fmt_node_as_vimhelp(fn['desc_node'])
+        if not doc and fn['brief_desc_node']:
+            doc = fmt_node_as_vimhelp(fn['brief_desc_node'])
         if not doc:
             doc = 'TODO: Documentation'
 
@@ -1006,7 +996,8 @@ def main(config, args):
                 stderr=(subprocess.STDOUT if debug else subprocess.DEVNULL))
         p.communicate(
             config.format(
-                input=CONFIG[target]['files'],
+                input=' '.join(
+                    [f'"{file}"' for file in CONFIG[target]['files']]),
                 output=output_dir,
                 filter=filter_cmd,
                 file_patterns=CONFIG[target]['file_patterns'])
@@ -1096,6 +1087,7 @@ def main(config, args):
             raise RuntimeError(
                 'found new modules "{}"; update the "section_order" map'.format(
                     set(sections).difference(CONFIG[target]['section_order'])))
+        first_section_tag = sections[CONFIG[target]['section_order'][0]][1]
 
         docs = ''
 
@@ -1121,7 +1113,8 @@ def main(config, args):
         doc_file = os.path.join(base_dir, 'runtime', 'doc',
                                 CONFIG[target]['filename'])
 
-        delete_lines_below(doc_file, CONFIG[target]['section_start_token'])
+        if os.path.exists(doc_file):
+            delete_lines_below(doc_file, first_section_tag)
         with open(doc_file, 'ab') as fp:
             fp.write(docs.encode('utf8'))