From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 17:16:04 +0000 Subject: feat(docs): replace lua2dox.lua Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change). --- test/functional/script/text_utils_spec.lua | 39 ++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 test/functional/script/text_utils_spec.lua (limited to 'test/functional/script/text_utils_spec.lua') diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua new file mode 100644 index 0000000000..c429d306d5 --- /dev/null +++ b/test/functional/script/text_utils_spec.lua @@ -0,0 +1,39 @@ +local helpers = require('test.functional.helpers')(after_each) +local exec_lua = helpers.exec_lua +local eq = helpers.eq + +local function md_to_vimdoc(text) + return exec_lua( + [[ + local text_utils = require('scripts/text_utils') + return text_utils.md_to_vimdoc(table.concat(..., '\n'), 0, 0, 70) + ]], + text + ) +end + +local function test(act, exp) + eq(table.concat(exp, '\n'), md_to_vimdoc(act)) +end + +describe('md_to_vimdoc', function() + before_each(function() + helpers.clear() + end) + + it('can render para after fenced code', function() + test({ + '- Para1', + ' ```', + ' code', + ' ```', + ' Para2', + }, { + '• Para1 >', + ' code', + '<', + ' Para2', + '', + }) + end) +end) -- cgit From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 27 Feb 2024 15:20:32 +0000 Subject: docs: improve/add documentation of Lua types - Added `@inlinedoc` so single use Lua types can be inlined into the functions docs. E.g. ```lua --- @class myopts --- @inlinedoc --- --- Documentation for some field --- @field somefield integer --- @param opts myOpts function foo(opts) end ``` Will be rendered as ``` foo(opts) Parameters: - {opts} (table) Object with the fields: - somefield (integer) Documentation for some field ``` - Marked many classes with with `@nodoc` or `(private)`. We can eventually introduce these when we want to. --- test/functional/script/text_utils_spec.lua | 59 ++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 20 deletions(-) (limited to 'test/functional/script/text_utils_spec.lua') diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua index c429d306d5..e644df92ae 100644 --- a/test/functional/script/text_utils_spec.lua +++ b/test/functional/script/text_utils_spec.lua @@ -2,18 +2,28 @@ local helpers = require('test.functional.helpers')(after_each) local exec_lua = helpers.exec_lua local eq = helpers.eq -local function md_to_vimdoc(text) +local function md_to_vimdoc(text, start_indent, indent, text_width) return exec_lua( [[ + local text, start_indent, indent, text_width = ... + start_indent = start_indent or 0 + indent = indent or 0 + text_width = text_width or 70 local text_utils = require('scripts/text_utils') - return text_utils.md_to_vimdoc(table.concat(..., '\n'), 0, 0, 70) + return text_utils.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width) ]], - text + text, + start_indent, + indent, + text_width ) end -local function test(act, exp) - eq(table.concat(exp, '\n'), md_to_vimdoc(act)) +local function test(what, act, exp, ...) + local argc, args = select('#', ...), { ... } + it(what, function() + eq(table.concat(exp, '\n'), md_to_vimdoc(act, unpack(args, 1, argc))) + end) end describe('md_to_vimdoc', function() @@ -21,19 +31,28 @@ describe('md_to_vimdoc', function() helpers.clear() end) - it('can render para after fenced code', function() - test({ - '- Para1', - ' ```', - ' code', - ' ```', - ' Para2', - }, { - '• Para1 >', - ' code', - '<', - ' Para2', - '', - }) - end) + test('can render para after fenced code', { + '- Para1', + ' ```', + ' code', + ' ```', + ' Para2', + }, { + '• Para1 >', + ' code', + '<', + ' Para2', + '', + }) + + test('start_indent only applies to first line', { + 'para1', + '', + 'para2', + }, { + 'para1', + '', + ' para2', + '', + }, 0, 10, 78) end) -- cgit From ade1b12f49c3b3914c74847d791eb90ea90b56b7 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 8 Mar 2024 12:25:18 +0000 Subject: docs: support inline markdown - Tags are now created with `[tag]()` - References are now created with `[tag]` - Code spans are no longer wrapped --- test/functional/script/text_utils_spec.lua | 2 ++ 1 file changed, 2 insertions(+) (limited to 'test/functional/script/text_utils_spec.lua') diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua index e644df92ae..190c617e1d 100644 --- a/test/functional/script/text_utils_spec.lua +++ b/test/functional/script/text_utils_spec.lua @@ -55,4 +55,6 @@ describe('md_to_vimdoc', function() ' para2', '', }, 0, 10, 78) + + test('inline 1', { '(`string`)' }, { '(`string`)', '' }) end) -- cgit