diff options
| -rw-r--r-- | runtime/doc/api-funcs.txt | 716 | ||||
| -rw-r--r-- | runtime/syntax/help.vim | 2 | ||||
| -rw-r--r-- | scripts/gen_api_vimdoc.py | 514 |
3 files changed, 1231 insertions, 1 deletions
diff --git a/runtime/doc/api-funcs.txt b/runtime/doc/api-funcs.txt new file mode 100644 index 0000000000..706941fd12 --- /dev/null +++ b/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:
\ No newline at end of file diff --git a/runtime/syntax/help.vim b/runtime/syntax/help.vim index b3c7f2a63e..41bb0b1938 100644 --- a/runtime/syntax/help.vim +++ b/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]-.>" diff --git a/scripts/gen_api_vimdoc.py b/scripts/gen_api_vimdoc.py new file mode 100644 index 0000000000..d7165187f4 --- /dev/null +++ b/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 : |