From 9624fffcfa141335f772938d8c441bdb300e04e6 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 24 Oct 2024 15:34:52 +0200 Subject: feat(docs): autogenerate default_config docs Problem: Docs are manually maintained everywhere for no good reason. Solution: - revert commit 9dc02492c4a457479f8a0ec7a65aac1852ff59c0 - provide a "gF" friendly link to the source --- scripts/docgen.lua | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) (limited to 'scripts/docgen.lua') diff --git a/scripts/docgen.lua b/scripts/docgen.lua index 719e711c..4a62562d 100644 --- a/scripts/docgen.lua +++ b/scripts/docgen.lua @@ -9,6 +9,11 @@ local function template(s, params) return (s:gsub('{{([^{}]+)}}', params)) end +--- "@/.../nvim-lspconfig/lua/lspconfig/util.lua" => "./util.lua" +local function relpath(p) + return p:gsub([=[.*[/\\]lua[/\\]lspconfig[/\\]]=], '') +end + local function map_list(t, func) local res = {} for i, v in ipairs(t) do @@ -140,11 +145,29 @@ local function make_lsp_sections() end return make_section(0, '\n', { map_sorted(template_def.default_config, function(k, v) - local description = ((docs or {}).default_config or {})[k] - if description and type(description) ~= 'string' then - description = inspect(description) - elseif not description and type(v) == 'function' then - description = 'see source file' + local description = template_def.default_config[k] + if type(v) ~= 'function' then + description = inspect(v) + else + local info = debug.getinfo(v) + local relname = relpath(info.source) + local file = assert(io.open(string.sub(info.source, 2), 'r')) + + local fnbody = '' + local linenr = 0 + for line in file:lines() do + linenr = linenr + 1 + if linenr >= info.linedefined and linenr <= info.lastlinedefined then + fnbody = ('%s\n%s'):format(fnbody, line) + end + end + io.close(file) + + description = ('-- Source (use "gF" to visit): %s:%d\n'):format( + relname, + info.linedefined, + string.gsub(fnbody, '.*function', 'function') + ) end return string.format('- `%s` : \n```lua\n%s\n```', k, description or inspect(v)) end), @@ -245,7 +268,7 @@ local function make_lsp_sections() if #preamble_parts > 0 then table.insert(preamble_parts, '') end - params.preamble = table.concat(preamble_parts, '\n') + params.preamble = vim.trim(table.concat(preamble_parts, '\n')) end return template(lsp_section_template, params) -- cgit v1.2.3-70-g09d2 From 903866024cd6c93a6acefd359329364234a65754 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 24 Oct 2024 17:05:21 +0200 Subject: feat(docs): autogenerate default_config docs Problem: debug.info() is useless for some functions because they point to util.lua Solution: Provide a path to the source code instead of trying to inline the source code. --- lua/lspconfig/configs/clangd.lua | 2 +- scripts/docgen.lua | 44 ++++++++++++++++++++-------------------- 2 files changed, 23 insertions(+), 23 deletions(-) (limited to 'scripts/docgen.lua') diff --git a/lua/lspconfig/configs/clangd.lua b/lua/lspconfig/configs/clangd.lua index ffee2af7..06c75095 100644 --- a/lua/lspconfig/configs/clangd.lua +++ b/lua/lspconfig/configs/clangd.lua @@ -68,7 +68,7 @@ return { }, }, offsetEncoding = { 'utf-8', 'utf-16' }, - } + }, }, commands = { ClangdSwitchSourceHeader = { diff --git a/scripts/docgen.lua b/scripts/docgen.lua index 4a62562d..22abc294 100644 --- a/scripts/docgen.lua +++ b/scripts/docgen.lua @@ -83,7 +83,7 @@ require'lspconfig'.{{config_name}}.setup{} ``` {{commands}} -**Default values:** +**Default config:** {{default_values}} ]] @@ -113,6 +113,8 @@ local function make_lsp_sections() map_sorted(configs, function(config_name, template_object) local template_def = template_object.config_def local docs = template_def.docs + -- "lua/lspconfig/configs/xx.lua" + local config_file = ('lua/lspconfig/configs/%s.lua'):format(config_name) local params = { config_name = config_name, @@ -145,31 +147,29 @@ local function make_lsp_sections() end return make_section(0, '\n', { map_sorted(template_def.default_config, function(k, v) - local description = template_def.default_config[k] if type(v) ~= 'function' then - description = inspect(v) - else - local info = debug.getinfo(v) - local relname = relpath(info.source) - local file = assert(io.open(string.sub(info.source, 2), 'r')) + return ('- `%s` :\n```lua\n%s\n```'):format(k, inspect(v)) + end - local fnbody = '' - local linenr = 0 - for line in file:lines() do - linenr = linenr + 1 - if linenr >= info.linedefined and linenr <= info.lastlinedefined then - fnbody = ('%s\n%s'):format(fnbody, line) - end + local file = assert(io.open(config_file, 'r')) + local linenr = 0 + -- Find the line where `default_config` is defined. + for line in file:lines() do + linenr = linenr + 1 + if line:find('%sdefault_config%s') then + break end - io.close(file) - - description = ('-- Source (use "gF" to visit): %s:%d\n'):format( - relname, - info.linedefined, - string.gsub(fnbody, '.*function', 'function') - ) end - return string.format('- `%s` : \n```lua\n%s\n```', k, description or inspect(v)) + io.close(file) + + -- XXX: "../" because the path is outside of the doc/ dir. + return ('- `%s` source (use "gF" to visit): [../%s:%d](../%s#L%d)\n'):format( + k, + config_file, + linenr, + config_file, + linenr + ) end), }) end, -- cgit v1.2.3-70-g09d2 From b2c90502d8dd15efd2de24e1536952e0cb4bca16 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 24 Oct 2024 17:24:01 +0200 Subject: feat(docs): improve formatting of generated docs --- scripts/docgen.lua | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) (limited to 'scripts/docgen.lua') diff --git a/scripts/docgen.lua b/scripts/docgen.lua index 22abc294..38b4fa3c 100644 --- a/scripts/docgen.lua +++ b/scripts/docgen.lua @@ -9,11 +9,6 @@ local function template(s, params) return (s:gsub('{{([^{}]+)}}', params)) end ---- "@/.../nvim-lspconfig/lua/lspconfig/util.lua" => "./util.lua" -local function relpath(p) - return p:gsub([=[.*[/\\]lua[/\\]lspconfig[/\\]]=], '') -end - local function map_list(t, func) local res = {} for i, v in ipairs(t) do @@ -140,15 +135,17 @@ local function make_lsp_sections() end, }) - params.default_values = make_section(2, '\n\n', { + params.default_values = make_section(2, '\n', { function() if not template_def.default_config then return end return make_section(0, '\n', { map_sorted(template_def.default_config, function(k, v) - if type(v) ~= 'function' then - return ('- `%s` :\n```lua\n%s\n```'):format(k, inspect(v)) + if type(v) == 'boolean' then + return ('- `%s` : `%s`'):format(k, v) + elseif type(v) ~= 'function' then + return ('- `%s` :\n ```lua\n%s\n ```'):format(k, indent(2, inspect(v))) end local file = assert(io.open(config_file, 'r')) @@ -163,7 +160,7 @@ local function make_lsp_sections() io.close(file) -- XXX: "../" because the path is outside of the doc/ dir. - return ('- `%s` source (use "gF" to visit): [../%s:%d](../%s#L%d)\n'):format( + return ('- `%s` source (use "gF" to visit): [../%s:%d](../%s#L%d)'):format( k, config_file, linenr, -- cgit v1.2.3-70-g09d2