mirror of
https://github.com/neovim/neovim.git
synced 2024-12-24 13:15:09 -07:00
gen_vimdoc.py: support lua/shared.lua module [ci skip]
This commit is contained in:
Justin M. Keyes
parent
53576dfb35
commit
e628c011bf
@ -30,7 +30,7 @@ finds and loads Lua modules. The conventions are similar to VimL plugins,
|
||||
with some extra features. See |lua-require-example| for a walkthrough.
|
||||
|
||||
==============================================================================
|
||||
Importing modules *lua-require*
|
||||
Importing Lua modules *lua-require*
|
||||
|
||||
Nvim automatically adjusts `package.path` and `package.cpath` according to
|
||||
effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is
|
||||
@ -325,9 +325,10 @@ Examples: >
|
||||
Note that currently second argument to `luaeval` undergoes VimL to lua
|
||||
conversion, so changing containers in lua do not affect values in VimL. Return
|
||||
value is also always converted. When converting, |msgpack-special-dict|s are
|
||||
treated specially.
|
||||
|
||||
==============================================================================
|
||||
vim.* *lua-vim* *lua-stdlib*
|
||||
Lua standard modules *lua-stdlib*
|
||||
|
||||
The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
|
||||
various functions and sub-modules. It is always loaded, thus require("vim")
|
||||
@ -361,7 +362,7 @@ Note that underscore-prefixed functions (e.g. "_os_proc_children") are
|
||||
internal/private and must not be used by plugins.
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
vim.api.* functions
|
||||
VIM.API *lua-api*
|
||||
|
||||
`vim.api` exposes the full Nvim |API| as a table of Lua functions.
|
||||
|
||||
@ -371,7 +372,7 @@ For example, to use the "nvim_get_current_line()" API function, call
|
||||
print(tostring(vim.api.nvim_get_current_line()))
|
||||
|
||||
------------------------------------------------------------------------------
|
||||
vim.* builtin functions
|
||||
VIM *lua-util*
|
||||
|
||||
vim.inspect({object}, {options}) *vim.inspect*
|
||||
Return a human-readable representation of the passed object. See
|
||||
@ -419,7 +420,7 @@ vim.types *lua-vim.types*
|
||||
only contain values for these three types.
|
||||
|
||||
==============================================================================
|
||||
Vim Lua Functions *lua-vim*
|
||||
Lua module: vim *lua-vim*
|
||||
|
||||
gsplit({s}, {sep}, {plain}) *vim.gsplit()*
|
||||
Split a string by a given separator. The separator can be a
|
||||
@ -442,11 +443,12 @@ gsplit({s}, {sep}, {plain}) *vim.gsplit()*
|
||||
split({s}, {sep}, {plain}) *vim.split()*
|
||||
Split a string by a given separator.
|
||||
|
||||
Examples:
|
||||
Examples: >
|
||||
|
||||
- split(":aa::b:", ":") returns {'','aa','','bb',''}
|
||||
- split("axaby", "ab?") returns {'','x','y'}
|
||||
- split(x*yz*o, "*", true) returns {'x','yz','o'}
|
||||
split(":aa::b:", ":") --> {'','aa','','bb',''}
|
||||
split("axaby", "ab?") --> {'','x','y'}
|
||||
split(x*yz*o, "*", true) --> {'x','yz','o'}
|
||||
<
|
||||
|
||||
Parameters: ~
|
||||
{s} String The string to split
|
||||
@ -483,4 +485,24 @@ deepcopy({orig}) *vim.deepcopy()*
|
||||
A new table where the keys and values are deepcopies of
|
||||
the keys and values from the original table.
|
||||
|
||||
|
||||
|
||||
|
||||
tbl_contains({t}, {value}) *vim.tbl_contains()*
|
||||
TODO: Documentation
|
||||
|
||||
tbl_extend({behavior}, {...}) *vim.tbl_extend()*
|
||||
Parameters: ~
|
||||
{behavior} Decides what to do if a key is found in more
|
||||
than one map:
|
||||
- "error": raise an error
|
||||
- "keep": use value from the leftmost map
|
||||
- "force": use value from the rightmost map
|
||||
|
||||
See also: ~
|
||||
|extend()|
|
||||
|
||||
tbl_flatten({t}) *vim.tbl_flatten()*
|
||||
TODO: Documentation
|
||||
|
||||
vim:tw=78:ts=8:ft=help:norl:
|
||||
|
||||
@ -16,14 +16,14 @@ local function tbl_contains(t, value)
|
||||
return false
|
||||
end
|
||||
|
||||
--- Merges two or more map-like tables.
|
||||
-- Merges two or more map-like tables.
|
||||
--
|
||||
--@see |extend()|
|
||||
--
|
||||
-- behavior: Decides what to do if a key is found in more than one map:
|
||||
-- "error": raise an error
|
||||
-- "keep": use value from the leftmost map
|
||||
-- "force": use value from the rightmost map
|
||||
--@param behavior Decides what to do if a key is found in more than one map:
|
||||
--- - "error": raise an error
|
||||
--- - "keep": use value from the leftmost map
|
||||
--- - "force": use value from the rightmost map
|
||||
local function tbl_extend(behavior, ...)
|
||||
if (behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force') then
|
||||
error('invalid "behavior": '..tostring(behavior))
|
||||
|
||||
@ -75,21 +75,36 @@ CONFIG = {
|
||||
'file_patterns': '*.h *.c',
|
||||
# Only function with this prefix are considered
|
||||
'func_name_prefix': 'nvim_',
|
||||
# Section name overrides.
|
||||
'section_name': {
|
||||
'vim.c': 'Global',
|
||||
},
|
||||
# Module name overrides (for Lua).
|
||||
'module_override': {},
|
||||
# Append the docs for these modules, do not start a new section.
|
||||
'append_only' : [],
|
||||
},
|
||||
'lua': {
|
||||
'filename': 'if_lua.txt',
|
||||
'section_start_token': '*vim-lua*',
|
||||
'section_start_token': '*lua-vim*',
|
||||
'section_order' : [
|
||||
'vim.lua',
|
||||
'shared.lua',
|
||||
],
|
||||
'files': os.path.join(base_dir, 'src/nvim/lua/vim.lua'),
|
||||
'files': ' '.join([
|
||||
os.path.join(base_dir, 'src/nvim/lua/vim.lua'),
|
||||
os.path.join(base_dir, 'runtime/lua/vim/shared.lua'),
|
||||
]),
|
||||
'file_patterns': '*.lua',
|
||||
'func_name_prefix': '',
|
||||
}
|
||||
}
|
||||
# Section name overrides.
|
||||
section_name = {
|
||||
'vim.c': 'Global',
|
||||
'section_name': {},
|
||||
'module_override': {
|
||||
'shared': 'vim', # `shared` functions are exposed on the `vim` module.
|
||||
},
|
||||
'append_only' : [
|
||||
'shared.lua',
|
||||
],
|
||||
},
|
||||
}
|
||||
|
||||
param_exclude = (
|
||||
@ -303,7 +318,7 @@ def render_node(n, text, prefix='', indent='', width=62):
|
||||
elif n.nodeName == 'listitem':
|
||||
for c in n.childNodes:
|
||||
text += indent + prefix + render_node(c, text, indent=indent+(' ' * len(prefix)), width=width)
|
||||
elif n.nodeName == 'para':
|
||||
elif n.nodeName in ('para', 'heading'):
|
||||
for c in n.childNodes:
|
||||
text += render_node(c, text, indent=indent, width=width)
|
||||
if is_inline(n):
|
||||
@ -466,9 +481,10 @@ def parse_source_xml(filename, mode):
|
||||
|
||||
if mode == 'lua':
|
||||
fstem = compoundname.split('.')[0]
|
||||
vimtag = '*%s.%s()*' % (fstem, name)
|
||||
fstem = CONFIG[mode]['module_override'].get(fstem, fstem)
|
||||
vimtag = '*{}.{}()*'.format(fstem, name)
|
||||
else:
|
||||
vimtag = '*%s()*' % name
|
||||
vimtag = '*{}()*'.format(name)
|
||||
|
||||
params = []
|
||||
type_length = 0
|
||||
@ -646,14 +662,14 @@ def gen_docs(config):
|
||||
|
||||
if doc:
|
||||
filename = os.path.basename(filename)
|
||||
name = section_name.get(filename, name)
|
||||
name = CONFIG[mode]['section_name'].get(filename, name)
|
||||
|
||||
if mode == 'lua':
|
||||
title = '%s Lua Functions' % name
|
||||
helptag = '*%s-lua*' % name.lower()
|
||||
title = 'Lua module: {}'.format(name.lower())
|
||||
helptag = '*lua-{}*'.format(name.lower())
|
||||
else:
|
||||
title = '%s Functions' % name
|
||||
helptag = '*api-%s*' % name.lower()
|
||||
title = '{} Functions'.format(name)
|
||||
helptag = '*api-{}*'.format(name.lower())
|
||||
sections[filename] = (title, helptag, doc)
|
||||
|
||||
if not sections:
|
||||
@ -664,23 +680,14 @@ def gen_docs(config):
|
||||
i = 0
|
||||
for filename in CONFIG[mode]['section_order']:
|
||||
if filename not in sections:
|
||||
continue
|
||||
raise RuntimeError('found new module "{}"; update the "section_order" map'.format(filename))
|
||||
title, helptag, section_doc = sections.pop(filename)
|
||||
|
||||
i += 1
|
||||
docs += sep
|
||||
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
|
||||
if filename not in CONFIG[mode]['append_only']:
|
||||
docs += sep
|
||||
docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
|
||||
docs += section_doc
|
||||
docs += '\n\n\n'
|
||||
docs += section_doc
|
||||
docs += '\n\n\n'
|
||||
|
||||
docs = docs.rstrip() + '\n\n'
|
||||
docs += ' vim:tw=78:ts=8:ft=help:norl:\n'
|
||||
|
||||
@ -203,12 +203,11 @@ end
|
||||
--- Split a string by a given separator.
|
||||
---
|
||||
--- Examples:
|
||||
---
|
||||
--- * split(":aa::b:", ":") returns {'','aa','','bb',''}
|
||||
---
|
||||
--- * split("axaby", "ab?") returns {'','x','y'}
|
||||
---
|
||||
--- * split(x*yz*o, "*", true) returns {'x','yz','o'}
|
||||
--- <pre>
|
||||
--- split(":aa::b:", ":") --> {'','aa','','bb',''}
|
||||
--- split("axaby", "ab?") --> {'','x','y'}
|
||||
--- split(x*yz*o, "*", true) --> {'x','yz','o'}
|
||||
--- </pre>
|
||||
---
|
||||
--@param s String The string to split
|
||||
--@param sep String The separator to use (see |vim.gsplit()|)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user