automation: Generate API documentation (#5798)

runtime: Add underscore to {} helpSpecial syntax pattern

docs: Added generated api-funcs.txt

runtime/doc/api-funcs.txt

@@ -0,0 +1,716 @@
+*api-funcs.txt*         Neovim API Function Reference                   {Nvim}
+
+Note: This documentation is generated from Neovim's API source code.
+
+Contents:
+
+1. Global Functions   |api-global|
+2. Buffer Functions   |api-buffer|
+3. Window Functions   |api-window|
+4. Tabpage Functions  |api-tabpage|
+5. UI Functions       |api-ui|
+
+==============================================================================
+1. Global Functions                                               *api-global*
+
+nvim_command({command})                                       *nvim_command()*
+                Executes an ex-command. On VimL error: Returns the VimL error;
+                v:errmsg is not updated.
+
+                Parameters:~
+                    {command}  Ex-command string
+
+nvim_feedkeys({keys}, {mode}, {escape_csi})                  *nvim_feedkeys()*
+                Passes input keys to Nvim. On VimL error: Does not fail, but
+                updates v:errmsg.
+
+                Parameters:~
+                    {keys}        to be typed
+                    {mode}        mapping options
+                    {escape_csi}  If true, escape K_SPECIAL/CSI bytes in
+                                  `keys`
+
+nvim_input({keys})                                              *nvim_input()*
+                Passes keys to Nvim as raw user-input. On VimL error: Does not
+                fail, but updates v:errmsg.
+
+                Unlike `nvim_feedkeys`, this uses a lower-level input buffer
+                and the call is not deferred. This is the most reliable way to
+                emulate real user input.
+
+                Parameters:~
+                    {keys}  to be typed
+
+                Return:~
+                    Number of bytes actually written (can be fewer than
+                    requested if the buffer becomes full).
+
+                                                    *nvim_replace_termcodes()*
+nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
+                Replaces any terminal codes with the internal representation
+
+nvim_command_output({str})                             *nvim_command_output()*
+                TODO: Documentation
+
+nvim_eval({expr})                                                *nvim_eval()*
+                Evaluates a VimL expression (:help expression). Dictionaries
+                and Lists are recursively expanded. On VimL error: Returns a
+                generic error; v:errmsg is not updated.
+
+                Parameters:~
+                    {expr}  VimL expression string
+
+                Return:~
+                    Evaluation result or expanded object
+
+nvim_call_function({fname}, {args})                     *nvim_call_function()*
+                Calls a VimL function with the given arguments. On VimL error:
+                Returns a generic error; v:errmsg is not updated.
+
+                Parameters:~
+                    {fname}  Function to call
+                    {args}   Function arguments packed in an Array
+
+                Return:~
+                    Result of the function call
+
+nvim_strwidth({str})                                         *nvim_strwidth()*
+                Calculates the number of display cells occupied by `text`.
+                <Tab> counts as one cell.
+
+                Parameters:~
+                    {text}  Some text
+
+                Return:~
+                    Number of cells
+
+nvim_list_runtime_paths()                          *nvim_list_runtime_paths()*
+                Gets the paths contained in 'runtimepath'.
+
+                Return:~
+                    List of paths
+
+nvim_set_current_dir({dir})                           *nvim_set_current_dir()*
+                Changes the global working directory.
+
+                Parameters:~
+                    {dir}  Directory path
+
+nvim_get_current_line()                              *nvim_get_current_line()*
+                Gets the current line
+
+                Parameters:~
+
+                Return:~
+                    Current line string
+
+nvim_set_current_line({line})                        *nvim_set_current_line()*
+                Sets the current line
+
+                Parameters:~
+                    {line}  Line contents
+
+nvim_del_current_line()                              *nvim_del_current_line()*
+                Deletes the current line
+
+                Parameters:~
+
+nvim_get_var({name})                                          *nvim_get_var()*
+                Gets a global (g:) variable
+
+                Parameters:~
+                    {name}  Variable name
+
+                Return:~
+                    Variable value
+
+nvim_set_var({name}, {value})                                 *nvim_set_var()*
+                Sets a global (g:) variable
+
+                Parameters:~
+                    {name}   Variable name
+                    {value}  Variable value
+
+nvim_del_var({name})                                          *nvim_del_var()*
+                Removes a global (g:) variable
+
+                Parameters:~
+                    {name}  Variable name
+
+nvim_get_vvar({name})                                        *nvim_get_vvar()*
+                Gets a v: variable
+
+                Parameters:~
+                    {name}  Variable name
+
+                Return:~
+                    Variable value
+
+nvim_get_option({name})                                    *nvim_get_option()*
+                Gets an option value string
+
+                Parameters:~
+                    {name}  Option name
+
+                Return:~
+                    Option value
+
+nvim_set_option({name}, {value})                           *nvim_set_option()*
+                Sets an option value
+
+                Parameters:~
+                    {name}   Option name
+                    {value}  New option value
+
+nvim_out_write({str})                                       *nvim_out_write()*
+                Writes a message to vim output buffer
+
+                Parameters:~
+                    {str}  Message
+
+nvim_err_write({str})                                       *nvim_err_write()*
+                Writes a message to vim error buffer
+
+                Parameters:~
+                    {str}  Message
+
+nvim_err_writeln({str})                                   *nvim_err_writeln()*
+                Writes a message to vim error buffer. Appends a linefeed to
+                ensure all contents are written.
+
+                Parameters:~
+                    {str}  Message
+
+nvim_list_bufs()                                            *nvim_list_bufs()*
+                Gets the current list of buffer handles
+
+                Return:~
+                    List of buffer handles
+
+nvim_get_current_buf()                                *nvim_get_current_buf()*
+                Gets the current buffer
+
+                Return:~
+                    Buffer handle
+
+nvim_set_current_buf({buffer})                        *nvim_set_current_buf()*
+                Sets the current buffer
+
+                Parameters:~
+                    {id}  Buffer handle
+
+nvim_list_wins()                                            *nvim_list_wins()*
+                Gets the current list of window handles
+
+                Return:~
+                    List of window handles
+
+nvim_get_current_win()                                *nvim_get_current_win()*
+                Gets the current window
+
+                Return:~
+                    Window handle
+
+nvim_set_current_win({window})                        *nvim_set_current_win()*
+                Sets the current window
+
+                Parameters:~
+                    {handle}  Window handle
+
+nvim_list_tabpages()                                    *nvim_list_tabpages()*
+                Gets the current list of tabpage handles
+
+                Return:~
+                    List of tabpage handles
+
+nvim_get_current_tabpage()                        *nvim_get_current_tabpage()*
+                Gets the current tabpage
+
+                Return:~
+                    Tabpage handle
+
+nvim_set_current_tabpage({tabpage})               *nvim_set_current_tabpage()*
+                Sets the current tabpage
+
+                Parameters:~
+                    {handle}  Tabpage handle
+
+nvim_subscribe({event})                                     *nvim_subscribe()*
+                Subscribes to event broadcasts
+
+                Parameters:~
+                    {event}  Event type string
+
+nvim_unsubscribe({event})                                 *nvim_unsubscribe()*
+                Unsubscribes to event broadcasts
+
+                Parameters:~
+                    {event}  Event type string
+
+nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
+                TODO: Documentation
+
+nvim_get_color_map()                                    *nvim_get_color_map()*
+                TODO: Documentation
+
+nvim_get_api_info()                                      *nvim_get_api_info()*
+                TODO: Documentation
+
+nvim_call_atomic({calls})                                 *nvim_call_atomic()*
+                Call many api methods atomically
+
+                This has two main usages: Firstly, to perform several requests
+                from an async context atomically, i.e. without processing
+                requests from other rpc clients or redrawing or allowing user
+                interaction in between. Note that api methods that could fire
+                autocommands or do event processing still might do so. For
+                instance invoking the :sleep command might call timer
+                callbacks. Secondly, it can be used to reduce rpc overhead
+                (roundtrips) when doing many requests in sequence.
+
+                Parameters:~
+                    {calls}  an array of calls, where each call is described
+                             by an array with two elements: the request name,
+                             and an array of arguments.
+
+                Return:~
+                    an array with two elements. The first is an array of
+                    return values. The second is NIL if all calls succeeded.
+                    If a call resulted in an error, it is a three-element
+                    array with the zero-based index of the call which resulted
+                    in an error, the error type and the error message. If an
+                    error ocurred, the values from all preceding calls will
+                    still be returned.
+
+
+==============================================================================
+2. Buffer Functions                                               *api-buffer*
+
+nvim_buf_line_count({buffer})                          *nvim_buf_line_count()*
+                Gets the buffer line count
+
+                Parameters:~
+                    {buffer}  Buffer handle
+
+                Return:~
+                    Line count
+
+                                                        *nvim_buf_get_lines()*
+nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
+                Retrieves a line range from the buffer
+
+                Indexing is zero-based, end-exclusive. Negative indices are
+                interpreted as length+1+index, i e -1 refers to the index past
+                the end. So to get the last element set start=-2 and end=-1.
+
+                Out-of-bounds indices are clamped to the nearest valid value,
+                unless `strict_indexing` is set.
+
+                Parameters:~
+                    {buffer}           Buffer handle
+                    {start}            First line index
+                    {end}              Last line index (exclusive)
+                    {strict_indexing}  Whether out-of-bounds should be an
+                                       error.
+
+                Return:~
+                    Array of lines
+
+                                                        *nvim_buf_set_lines()*
+nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
+                   {replacement})
+                Replaces line range on the buffer
+
+                Indexing is zero-based, end-exclusive. Negative indices are
+                interpreted as length+1+index, i e -1 refers to the index past
+                the end. So to change or delete the last element set start=-2
+                and end=-1.
+
+                To insert lines at a given index, set both start and end to
+                the same index. To delete a range of lines, set replacement to
+                an empty array.
+
+                Out-of-bounds indices are clamped to the nearest valid value,
+                unless `strict_indexing` is set.
+
+                Parameters:~
+                    {buffer}           Buffer handle
+                    {start}            First line index
+                    {end}              Last line index (exclusive)
+                    {strict_indexing}  Whether out-of-bounds should be an
+                                       error.
+                    {replacement}      Array of lines to use as replacement
+
+nvim_buf_get_var({buffer}, {name})                        *nvim_buf_get_var()*
+                Gets a buffer-scoped (b:) variable.
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Variable name
+
+                Return:~
+                    Variable value
+
+nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
+                Sets a buffer-scoped (b:) variable
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Variable name
+                    {value}   Variable value
+
+nvim_buf_del_var({buffer}, {name})                        *nvim_buf_del_var()*
+                Removes a buffer-scoped (b:) variable
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Variable name
+
+nvim_buf_get_option({buffer}, {name})                  *nvim_buf_get_option()*
+                Gets a buffer option value
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Option name
+
+                Return:~
+                    Option value
+
+nvim_buf_set_option({buffer}, {name}, {value})         *nvim_buf_set_option()*
+                Sets a buffer option value. Passing 'nil' as value deletes the
+                option (only works if there's a global fallback)
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Option name
+                    {value}   Option value
+
+nvim_buf_get_number({buffer})                          *nvim_buf_get_number()*
+                Gets the buffer number
+
+                Parameters:~
+                    {buffer}  Buffer handle
+
+                Return:~
+                    Buffer number
+
+nvim_buf_get_name({buffer})                              *nvim_buf_get_name()*
+                Gets the full file name for the buffer
+
+                Parameters:~
+                    {buffer}  Buffer handle
+
+                Return:~
+                    Buffer name
+
+nvim_buf_set_name({buffer}, {name})                      *nvim_buf_set_name()*
+                Sets the full file name for a buffer
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Buffer name
+
+nvim_buf_is_valid({buffer})                              *nvim_buf_is_valid()*
+                Checks if a buffer is valid
+
+                Parameters:~
+                    {buffer}  Buffer handle
+
+                Return:~
+                    true if the buffer is valid, false otherwise
+
+nvim_buf_get_mark({buffer}, {name})                      *nvim_buf_get_mark()*
+                Return a tuple (row,col) representing the position of the
+                named mark
+
+                Parameters:~
+                    {buffer}  Buffer handle
+                    {name}    Mark name
+
+                Return:~
+                    (row, col) tuple
+
+                                                    *nvim_buf_add_highlight()*
+nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
+                       {col_start}, {col_end})
+                Adds a highlight to buffer.
+
+                This can be used for plugins which dynamically generate
+                highlights to a buffer (like a semantic highlighter or
+                linter). The function adds a single highlight to a buffer.
+                Unlike matchaddpos() highlights follow changes to line
+                numbering (as lines are inserted/removed above the highlighted
+                line), like signs and marks do.
+
+                "src_id" is useful for batch deletion/updating of a set of
+                highlights. When called with src_id = 0, an unique source id
+                is generated and returned. Succesive calls can pass in it as
+                "src_id" to add new highlights to the same source group. All
+                highlights in the same group can then be cleared with
+                nvim_buf_clear_highlight. If the highlight never will be
+                manually deleted pass in -1 for "src_id".
+
+                If "hl_group" is the empty string no highlight is added, but a
+                new src_id is still returned. This is useful for an external
+                plugin to synchrounously request an unique src_id at
+                initialization, and later asynchronously add and clear
+                highlights in response to buffer changes.
+
+                Parameters:~
+                    {buffer}     Buffer handle
+                    {src_id}     Source group to use or 0 to use a new group,
+                                 or -1 for ungrouped highlight
+                    {hl_group}   Name of the highlight group to use
+                    {line}       Line to highlight
+                    {col_start}  Start of range of columns to highlight
+                    {col_end}    End of range of columns to highlight, or -1
+                                 to highlight to end of line
+
+                Return:~
+                    The src_id that was used
+
+                                                  *nvim_buf_clear_highlight()*
+nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
+                Clears highlights from a given source group and a range of
+                lines
+
+                To clear a source group in the entire buffer, pass in 1 and -1
+                to line_start and line_end respectively.
+
+                Parameters:~
+                    {buffer}      Buffer handle
+                    {src_id}      Highlight source group to clear, or -1 to
+                                  clear all.
+                    {line_start}  Start of range of lines to clear
+                    {line_end}    End of range of lines to clear (exclusive)
+                                  or -1 to clear to end of file.
+
+
+==============================================================================
+3. Window Functions                                               *api-window*
+
+nvim_win_get_buf({window})                                *nvim_win_get_buf()*
+                Gets the current buffer in a window
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    Buffer handle
+
+nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
+                Gets the cursor position in the window
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    (row, col) tuple
+
+nvim_win_set_cursor({window}, {pos})                   *nvim_win_set_cursor()*
+                Sets the cursor position in the window
+
+                Parameters:~
+                    {window}  Window handle
+                    {pos}     (row, col) tuple representing the new position
+
+nvim_win_get_height({window})                          *nvim_win_get_height()*
+                Gets the window height
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    Height as a count of rows
+
+nvim_win_set_height({window}, {height})                *nvim_win_set_height()*
+                Sets the window height. This will only succeed if the screen
+                is split horizontally.
+
+                Parameters:~
+                    {window}  Window handle
+                    {height}  Height as a count of rows
+
+nvim_win_get_width({window})                            *nvim_win_get_width()*
+                Gets the window width
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    Width as a count of columns
+
+nvim_win_set_width({window}, {width})                   *nvim_win_set_width()*
+                Sets the window width. This will only succeed if the screen is
+                split vertically.
+
+                Parameters:~
+                    {window}  Window handle
+                    {width}   Width as a count of columns
+
+nvim_win_get_var({window}, {name})                        *nvim_win_get_var()*
+                Gets a window-scoped (w:) variable
+
+                Parameters:~
+                    {window}  Window handle
+                    {name}    Variable name
+
+                Return:~
+                    Variable value
+
+nvim_win_set_var({window}, {name}, {value})               *nvim_win_set_var()*
+                Sets a window-scoped (w:) variable
+
+                Parameters:~
+                    {window}  Window handle
+                    {name}    Variable name
+                    {value}   Variable value
+
+nvim_win_del_var({window}, {name})                        *nvim_win_del_var()*
+                Removes a window-scoped (w:) variable
+
+                Parameters:~
+                    {window}  Window handle
+                    {name}    Variable name
+
+nvim_win_get_option({window}, {name})                  *nvim_win_get_option()*
+                Gets a window option value
+
+                Parameters:~
+                    {window}  Window handle
+                    {name}    Option name
+
+                Return:~
+                    Option value
+
+nvim_win_set_option({window}, {name}, {value})         *nvim_win_set_option()*
+                Sets a window option value. Passing 'nil' as value deletes the
+                option(only works if there's a global fallback)
+
+                Parameters:~
+                    {window}  Window handle
+                    {name}    Option name
+                    {value}   Option value
+
+nvim_win_get_position({window})                      *nvim_win_get_position()*
+                Gets the window position in display cells. First position is
+                zero.
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    (row, col) tuple with the window position
+
+nvim_win_get_tabpage({window})                        *nvim_win_get_tabpage()*
+                Gets the window tabpage
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    Tabpage that contains the window
+
+nvim_win_get_number({window})                          *nvim_win_get_number()*
+                Gets the window number
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    Window number
+
+nvim_win_is_valid({window})                              *nvim_win_is_valid()*
+                Checks if a window is valid
+
+                Parameters:~
+                    {window}  Window handle
+
+                Return:~
+                    true if the window is valid, false otherwise
+
+
+==============================================================================
+4. Tabpage Functions                                             *api-tabpage*
+
+nvim_tabpage_list_wins({tabpage})                   *nvim_tabpage_list_wins()*
+                Gets the windows in a tabpage
+
+                Parameters:~
+                    {tabpage}  Tabpage
+
+                Return:~
+                    List of windows in tabpage
+
+nvim_tabpage_get_var({tabpage}, {name})               *nvim_tabpage_get_var()*
+                Gets a tab-scoped (t:) variable
+
+                Parameters:~
+                    {tabpage}  Tabpage handle
+                    {name}     Variable name
+
+                Return:~
+                    Variable value
+
+nvim_tabpage_set_var({tabpage}, {name}, {value})      *nvim_tabpage_set_var()*
+                Sets a tab-scoped (t:) variable
+
+                Parameters:~
+                    {tabpage}  Tabpage handle
+                    {name}     Variable name
+                    {value}    Variable value
+
+nvim_tabpage_del_var({tabpage}, {name})               *nvim_tabpage_del_var()*
+                Removes a tab-scoped (t:) variable
+
+                Parameters:~
+                    {tabpage}  Tabpage handle
+                    {name}     Variable name
+
+nvim_tabpage_get_win({tabpage})                       *nvim_tabpage_get_win()*
+                Gets the current window in a tabpage
+
+                Parameters:~
+                    {tabpage}  Tabpage handle
+
+                Return:~
+                    Window handle
+
+nvim_tabpage_get_number({tabpage})                 *nvim_tabpage_get_number()*
+                Gets the tabpage number
+
+                Parameters:~
+                    {tabpage}  Tabpage handle
+
+                Return:~
+                    Tabpage number
+
+nvim_tabpage_is_valid({tabpage})                     *nvim_tabpage_is_valid()*
+                Checks if a tabpage is valid
+
+                Parameters:~
+                    {tabpage}  Tabpage handle
+
+                Return:~
+                    true if the tabpage is valid, false otherwise
+
+
+==============================================================================
+5. UI Functions                                                       *api-ui*
+
+remote_ui_disconnect()                                *remote_ui_disconnect()*
+                TODO: Documentation
+
+nvim_ui_attach({width}, {height}, {options})                *nvim_ui_attach()*
+                TODO: Documentation
+
+nvim_ui_detach()                                            *nvim_ui_detach()*
+                TODO: Documentation
+
+nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
+                TODO: Documentation
+
+nvim_ui_set_option({name}, {value})                     *nvim_ui_set_option()*
+                TODO: Documentation
+
+ vim:tw=78:ts=8:ft=help:norl:

runtime/syntax/help.vim

@@ -59,7 +59,7 @@ syn match helpSpecial		"\[N]"
 syn match helpSpecial		"N  N"he=s+1
 syn match helpSpecial		"Nth"me=e-2
 syn match helpSpecial		"N-1"me=e-2
-syn match helpSpecial		"{[-a-zA-Z0-9'"*+/:%#=[\]<>.,]\+}"
+syn match helpSpecial		"{[-_a-zA-Z0-9'"*+/:%#=[\]<>.,]\+}"
 syn match helpSpecial		"\s\[[-a-z^A-Z0-9_]\{2,}]"ms=s+1
 syn match helpSpecial		"<[-a-zA-Z0-9_]\+>"
 syn match helpSpecial		"<[SCM]-.>"

scripts/gen_api_vimdoc.py

@@ -0,0 +1,514 @@
+#!/usr/bin/env python
+"""Parses Doxygen XML output to generate Neovim's API documentation.
+
+This would be easier using lxml and XSLT, but:
+
+  1. This should avoid needing Python dependencies, especially ones that are
+     C modules that have library dependencies (lxml requires libxml and
+     libxslt).
+  2. I wouldn't know how to deal with nested indentation in <para> tags using
+     XSLT.
+
+Each function documentation is formatted with the following rules:
+
+  - Maximum width of 78 characters (`text_width`).
+  - Spaces for indentation.
+  - Function signature and helptag are on the same line.
+    - Helptag is right aligned.
+    - Signature and helptag must have a minimum of 8 spaces between them.
+    - If the signature is too long, it is placed on the line after the
+      helptag.  The signature wraps at `text_width - 8` characters with
+      subsequent lines indented to the open parenthesis.
+  - Documentation body will be indented by 16 spaces.
+    - Subsection bodies are indented an additional 4 spaces.
+  - Documentation body consists of the function description, parameter details,
+    return description, and C declaration.
+  - Parameters are omitted for the `void` and `Error *` types, or if the
+    parameter is marked as [out].
+  - Each function documentation is separated by a single line.
+
+The C declaration is added to the end to show actual argument types.
+"""
+import os
+import re
+import sys
+import shutil
+import textwrap
+import subprocess
+
+from xml.dom import minidom
+
+# Text at the top of the doc file.
+preamble = '''
+Note: This documentation is generated from Neovim's API source code.
+'''
+
+doc_filename = 'api-funcs.txt'
+
+# Section name overrides.
+section_name = {
+    'vim.c': 'Global',
+}
+
+# Section ordering.
+section_order = (
+    'vim.c',
+    'buffer.c',
+    'window.c',
+    'tabpage.c',
+    'ui.c',
+)
+
+param_exclude = (
+    'channel_id',
+)
+
+text_width = 78
+script_path = os.path.abspath(__file__)
+base_dir = os.path.dirname(os.path.dirname(script_path))
+src_dir = os.path.join(base_dir, 'src/nvim/api')
+out_dir = os.path.join(base_dir, 'tmp/api_doc')
+filter_cmd = '%s %s' % (sys.executable, script_path)
+seen_funcs = set()
+
+# Tracks `xrefsect` titles.  As of this writing, used only for separating
+# deprecated functions.
+xrefs = set()
+
+
+# XML Parsing Utilities {{{
+def find_first(parent, name):
+    """Finds the first matching node within parent."""
+    sub = parent.getElementsByTagName(name)
+    if not sub:
+        return None
+    return sub[0]
+
+
+def get_children(parent, name):
+    """Yield matching child nodes within parent."""
+    for child in parent.childNodes:
+        if child.nodeType == child.ELEMENT_NODE and child.nodeName == name:
+            yield child
+
+
+def get_child(parent, name):
+    """Get the first matching child node."""
+    for child in get_children(parent, name):
+        return child
+    return None
+
+
+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.
+
+    The beginning and end of the string is trimmed.  Empty lines are collapsed.
+    """
+    return re.sub(r'\A\n\s*\n*|\n\s*\n*\Z', '', re.sub(r'(\n\s*\n+)+', '\n\n', text))
+
+
+def get_text(parent):
+    """Combine all text in a node."""
+    if parent.nodeType == parent.TEXT_NODE:
+        return parent.data
+
+    out = ''
+    for node in parent.childNodes:
+        if node.nodeType == node.TEXT_NODE:
+            out += clean_text(node.data)
+        elif node.nodeType == node.ELEMENT_NODE:
+            out += ' ' + get_text(node)
+    return out
+
+
+def doc_wrap(text, prefix='', width=70, func=False):
+    """Wraps text to `width`.
+
+    The first line is prefixed with `prefix`, and subsequent lines are aligned.
+    If `func` is True, only wrap at commas.
+    """
+    if not width:
+        return text
+
+    indent_space = ' ' * len(prefix)
+
+    if func:
+        lines = [prefix]
+        for part in text.split(', '):
+            if part[-1] not in ');':
+                part += ', '
+            if len(lines[-1]) + len(part) > width:
+                lines.append(indent_space)
+            lines[-1] += part
+        return '\n'.join(x.rstrip() for x in lines).rstrip()
+
+    return '\n'.join(textwrap.wrap(text.strip(), width=width,
+                                   initial_indent=prefix,
+                                   subsequent_indent=indent_space))
+
+
+def parse_params(parent, width=62):
+    """Parse Doxygen `parameterlist`."""
+    name_length = 0
+    items = []
+    for child in parent.childNodes:
+        if child.nodeType == child.TEXT_NODE:
+            continue
+
+        name_node = find_first(child, 'parametername')
+        if name_node.getAttribute('direction') == 'out':
+            continue
+
+        name = get_text(name_node)
+        if name in param_exclude:
+            continue
+
+        name = '{%s}' % name
+        name_length = max(name_length, len(name) + 2)
+
+        desc = ''
+        desc_node = get_child(child, 'parameterdescription')
+        if desc_node:
+            desc = parse_parblock(desc_node, width=None)
+        items.append((name.strip(), desc.strip()))
+
+    out = 'Parameters:~\n'
+    for name, desc in items:
+        name = '    %s' % name.ljust(name_length)
+        out += doc_wrap(desc, prefix=name, width=width) + '\n'
+    return out.strip()
+
+
+def parse_para(parent, width=62):
+    """Parse doxygen `para` tag.
+
+    I assume <para> is a paragraph block or "a block of text".  It can contain
+    text nodes, or other tags.
+    """
+    line = ''
+    lines = []
+    for child in parent.childNodes:
+        if child.nodeType == child.TEXT_NODE:
+            line += child.data
+        elif child.nodeName == 'computeroutput':
+            line += '`%s`' % get_text(child)
+        else:
+            if line:
+                lines.append(doc_wrap(line, width=width))
+                line = ''
+
+            if child.nodeName == 'parameterlist':
+                lines.append(parse_params(child, width=width))
+            elif child.nodeName == 'xrefsect':
+                title = get_text(get_child(child, 'xreftitle'))
+                xrefs.add(title)
+                xrefdesc = parse_para(get_child(child, 'xrefdescription'))
+                lines.append(doc_wrap(xrefdesc, prefix='%s: ' % title,
+                                      width=width) + '\n')
+            elif child.nodeName == 'simplesect':
+                kind = child.getAttribute('kind')
+                if kind == 'return':
+                    lines.append('%s:~' % kind.title())
+                    lines.append(doc_wrap(parse_para(child),
+                                          prefix='    ',
+                                          width=width))
+            else:
+                lines.append(get_text(child))
+
+    if line:
+        lines.append(doc_wrap(line, width=width))
+    return clean_lines('\n'.join(lines).strip())
+
+
+def parse_parblock(parent, width=62):
+    """Parses a nested block of `para` tags.
+
+    Named after the \parblock command, but not directly related.
+    """
+    paragraphs = []
+    for child in parent.childNodes:
+        if child.nodeType == child.TEXT_NODE:
+            paragraphs.append(doc_wrap(child.data, width=width))
+        elif child.nodeName == 'para':
+            paragraphs.append(parse_para(child, width=width))
+        else:
+            paragraphs.append(doc_wrap(get_text(child), width=width))
+        paragraphs.append('')
+    return clean_lines('\n'.join(paragraphs).strip())
+# }}}
+
+
+def parse_source_xml(filename):
+    """Collects API functions.
+
+    This returns two strings:
+      1. The API functions
+      2. The deprecated API functions
+
+    The caller decides what to do with the deprecated documentation.
+    """
+    global xrefs
+    xrefs = set()
+    functions = []
+    deprecated_functions = []
+
+    dom = minidom.parse(filename)
+    for member in dom.getElementsByTagName('memberdef'):
+        if member.getAttribute('static') == 'yes' or \
+                member.getAttribute('kind') != 'function':
+            continue
+
+        loc = find_first(member, 'location')
+        if 'private' in loc.getAttribute('file'):
+            continue
+
+        return_type = get_text(get_child(member, 'type'))
+        if return_type == '':
+            continue
+
+        if return_type.startswith(('ArrayOf', 'DictionaryOf')):
+            parts = return_type.strip('_').split('_')
+            return_type = '%s(%s)' % (parts[0], ', '.join(parts[1:]))
+
+        name = get_text(get_child(member, 'name'))
+
+        vimtag = '*%s()*' % name
+        args = []
+        type_length = 0
+
+        for param in get_children(member, 'param'):
+            arg_type = get_text(get_child(param, 'type')).strip()
+            arg_name = ''
+            declname = get_child(param, 'declname')
+            if declname:
+                arg_name = get_text(declname).strip()
+
+            if arg_name in param_exclude:
+                continue
+
+            if arg_type.endswith('*'):
+                arg_type = arg_type.strip('* ')
+                arg_name = '*' + arg_name
+            type_length = max(type_length, len(arg_type))
+            args.append((arg_type, arg_name))
+
+        c_args = []
+        for arg_type, arg_name in args:
+            c_args.append('    ' + (
+                '%s %s' % (arg_type.ljust(type_length), arg_name)).strip())
+
+        c_decl = textwrap.indent('%s %s(\n%s\n);' % (return_type, name,
+                                                     ',\n'.join(c_args)),
+                                 '    ')
+
+        prefix = '%s(' % name
+        suffix = '%s)' % ', '.join('{%s}' % a[1] for a in args
+                                   if a[0] not in ('void', 'Error'))
+
+        # Minimum 8 chars between signature and vimtag
+        lhs = (text_width - 8) - len(prefix)
+
+        if len(prefix) + len(suffix) > lhs:
+            signature = vimtag.rjust(text_width) + '\n'
+            signature += doc_wrap(suffix, width=text_width-8, prefix=prefix,
+                                  func=True)
+        else:
+            signature = prefix + suffix
+            signature += vimtag.rjust(text_width - len(signature))
+
+        doc = ''
+        desc = find_first(member, 'detaileddescription')
+        if desc:
+            doc = parse_parblock(desc)
+            if 'DEBUG' in os.environ:
+                print(textwrap.indent(
+                    re.sub(r'\n\s*\n+', '\n',
+                           desc.toprettyxml(indent='  ', newl='\n')), ' ' * 16))
+
+        if not doc:
+            doc = 'TODO: Documentation'
+
+        if 'INCLUDE_C_DECL' in os.environ:
+            doc += '\n\nC Declaration:~\n>\n'
+            doc += c_decl
+            doc += '\n<'
+
+        func_doc = signature + '\n'
+        func_doc += textwrap.indent(clean_lines(doc), ' ' * 16)
+        func_doc = re.sub(r'^\s+([<>])$', r'\1', func_doc, flags=re.M)
+
+        if 'Deprecated' in xrefs:
+            deprecated_functions.append(func_doc)
+        else:
+            functions.append(func_doc)
+
+        xrefs.clear()
+
+    return '\n\n'.join(functions), '\n\n'.join(deprecated_functions)
+
+
+def gen_docs(config):
+    """Generate documentation.
+
+    Doxygen is called and configured through stdin.
+    """
+    p = subprocess.Popen(['doxygen', '-'], stdin=subprocess.PIPE)
+    p.communicate(config.format(input=src_dir, output=out_dir,
+                                filter=filter_cmd).encode('utf8'))
+    if p.returncode:
+        sys.exit(p.returncode)
+
+    title_length = 0
+    sections = {}
+    sep = '=' * text_width
+
+    base = os.path.join(out_dir, 'xml')
+    dom = minidom.parse(os.path.join(base, 'index.xml'))
+    for compound in dom.getElementsByTagName('compound'):
+        if compound.getAttribute('kind') != 'file':
+            continue
+
+        filename = get_text(find_first(compound, 'name'))
+        if filename.endswith('.c'):
+            functions, deprecated = parse_source_xml(
+                os.path.join(base, '%s.xml' % compound.getAttribute('refid')))
+
+            if not functions and not deprecated:
+                continue
+
+            if functions or deprecated:
+                name = os.path.splitext(os.path.basename(filename))[0]
+                if name == 'ui':
+                    name = name.upper()
+                else:
+                    name = name.title()
+
+                doc = ''
+                if functions:
+                    doc += '\n\n' + functions
+
+                if 'INCLUDE_DEPRECATED' in os.environ and deprecated:
+                    doc += '\n\n\nDeprecated %s Functions:~\n\n' % name
+                    doc += deprecated
+
+                if doc:
+                    filename = os.path.basename(filename)
+                    name = section_name.get(filename, name)
+                    title = '%s Functions' % name
+                    helptag = '*api-%s*' % name.lower()
+                    title_length = max(title_length, len(title))
+                    sections[filename] = (title, helptag, doc)
+
+    if not sections:
+        return
+
+    title_left = '*%s*' % doc_filename
+    title_center = 'Neovim API Function Reference'
+    title_right = '{Nvim}'
+    margin = max(len(title_left), len(title_right))
+    head = (title_left.ljust(margin) +
+            title_center.center(text_width - margin * 2) +
+            title_right.rjust(margin)) + '\n'
+
+    head += '\n%s\n\n' % doc_wrap(preamble, width=text_width)
+    head += 'Contents:\n\n'
+
+    docs = ''
+
+    title_length += len(str(len(section_order))) + 2
+    i = 0
+    for filename in section_order:
+        if filename not in sections:
+            continue
+        title, helptag, section_doc = sections.pop(filename)
+
+        i += 1
+        docs += sep
+        title = '%d. %s' % (i, title)
+        head += (title.ljust(title_length) + '  ' +
+                 helptag.replace('*', '|') + '\n')
+        docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
+        docs += section_doc
+        docs += '\n\n\n'
+
+    if sections:
+        # In case new API sources are added without updating the order dict.
+        for title, helptag, section_doc in sections.values():
+            i += 1
+            docs += sep
+            title = '%d. %s' % (i, title)
+            head += (title.ljust(title_length) + '  ' +
+                     helptag.replace('*', '|') + '\n')
+            docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
+            docs += section_doc
+            docs += '\n\n\n'
+
+    docs = '%s\n%s' % (head, docs)
+    docs = docs.rstrip() + '\n\n'
+    docs += ' vim:tw=78:ts=8:ft=help:norl:'
+
+    doc_file = os.path.join(base_dir, 'runtime/doc', doc_filename)
+    with open(doc_file, 'wb') as fp:
+        fp.write(docs.encode('utf8'))
+
+    shutil.rmtree(out_dir)
+
+
+def filter_source(filename):
+    """Filters the source to fix macros that confuse Doxygen."""
+    with open(filename, 'rt') as fp:
+        print(re.sub(r'^(ArrayOf|DictionaryOf)(\(.*?\))',
+                     lambda m: m.group(1)+'_'.join(
+                         re.split(r'[^\w]+', m.group(2))),
+                     fp.read(), flags=re.M))
+
+
+# Doxygen Config {{{
+Doxyfile = '''
+OUTPUT_DIRECTORY       = {output}
+INPUT                  = {input}
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.h *.c
+RECURSIVE              = YES
+INPUT_FILTER           = "{filter}"
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = */private/*
+EXCLUDE_SYMBOLS        =
+
+GENERATE_HTML          = NO
+GENERATE_DOCSET        = NO
+GENERATE_HTMLHELP      = NO
+GENERATE_QHP           = NO
+GENERATE_TREEVIEW      = NO
+GENERATE_LATEX         = NO
+GENERATE_RTF           = NO
+GENERATE_MAN           = NO
+GENERATE_DOCBOOK       = NO
+GENERATE_AUTOGEN_DEF   = NO
+
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = NO
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+'''
+# }}}
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1:
+        filter_source(sys.argv[1])
+    else:
+        gen_docs(Doxyfile)
+
+# vim: set ft=python ts=4 sw=4 tw=79 et fdm=marker :