From b1e074ccb5e0534ef525550aa5005f51cbc33697 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 24 Dec 2024 18:05:53 -0400 Subject: [PATCH 1/3] fix: make lua implemented hilbish interfaces documented --- cmd/docgen/docgen.lua | 52 +++++++++++--- docs/api/hilbish/hilbish.runner.md | 112 ++++++++++++++++++++++++----- docs/nature/dirs.md | 10 +-- nature/runner.lua | 2 +- 4 files changed, 146 insertions(+), 30 deletions(-) diff --git a/cmd/docgen/docgen.lua b/cmd/docgen/docgen.lua index 207357a..50e777c 100644 --- a/cmd/docgen/docgen.lua +++ b/cmd/docgen/docgen.lua @@ -1,6 +1,6 @@ local fs = require 'fs' local emmyPattern = '^%-%-%- (.+)' -local modpattern = '^%-+ @module (%w+)' +local modpattern = '^%-+ @module (.+)' local pieces = {} local files = fs.readdir 'nature' @@ -19,6 +19,8 @@ for _, fname in ipairs(files) do local docPiece = {} local lines = {} local lineno = 0 + local tocPos + local tocSearch = false for line in f:lines() do lineno = lineno + 1 lines[lineno] = line @@ -81,30 +83,64 @@ description: %s layout: doc menu: docs: - parent: "Nature" + parent: "%s" --- ]] for iface, dps in pairs(pieces) do local mod = iface:match '(%w+)%.' or 'nature' - local path = string.format('docs/%s/%s.md', mod, iface) + local docParent = 'Nature' + + path = string.format('docs/%s/%s.md', mod, iface) + if mod ~= 'nature' then + docParent = "API" + path = string.format('docs/api/%s/%s.md', mod, iface) + end + fs.mkdir(fs.dir(path), true) - local f = io.open(path, 'w') - f:write(string.format(header, 'Module', iface, 'No description.')) + + local exists = pcall(fs.stat, path) + local newOrNotNature = exists and mod ~= 'nature' + + local f = io.open(path, newOrNotNature and 'r+' or 'w+') + if not newOrNotNature then + f:write(string.format(header, 'Module', iface, 'No description.', docParent)) + end print(f) - print(mod, path) + print('mod and path:', mod, path) + + local tocSearch = false + local tocPos + for line in f:lines() do + if line:match '^## Functions' then + tocSearch = true + end + if tocSearch and line == '' then + tocSearch = false + tocPos = f:seek() - 1 + end + end for func, docs in pairs(dps) do - f:write(string.format('
\n
', func)) local sig = string.format('%s.%s(', iface, func) for idx, param in ipairs(docs.params) do sig = sig .. ((param.name:gsub('%?$', ''))) if idx ~= #docs.params then sig = sig .. ', ' end end sig = sig .. ')' - f:write(string.format([[ + + if tocPos then + local pos = f:seek() + f:seek('set', tocPos) + f:write(string.format('||%s|\n', func, docs.description[1])) + tocPos = f:seek() + f:seek('set', pos) + end + + f:write(string.format('
\n
\n', func)) + f:write(string.format([[

%s diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 8c89a52..7fb18e9 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -57,22 +57,13 @@ end) |setMode(cb)|This is the same as the `hilbish.runnerMode` function.| |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| - -
-
-

-hilbish.runner.setMode(cb) - - - -

- -This is the same as the `hilbish.runnerMode` function. -It takes a callback, which will be used to execute all interactive input. -In normal cases, neither callbacks should be overrided by the user, -as the higher level functions listed below this will handle it. - -#### Parameters +||Returns the current runner by name.| +||Sets the current interactive/command line runner mode.| +||Adds a runner to the table of available runners. If runner is a table,| +||Get a runner by name.| +||Sets a runner by name. The runner table must have the run function in it.| +||Executes cmd with a runner. If runnerName isn't passed, it uses| +### Parameters `function` **`cb`** @@ -114,3 +105,92 @@ This is the equivalent of using `source`.
+
+
+

+hilbish.runner.getCurrent() + + + +

+ +Returns the current runner by name. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.runner.setCurrent(name) + + + +

+ +Sets the current interactive/command line runner mode. +#### Parameters +`name` **`string`** +
+ +
+
+

+hilbish.runner.add(name, runner) + + + +

+ +Adds a runner to the table of available runners. If runner is a table, +it must have the run function in it. +#### Parameters +`name` **`string`** +`runner` **`function`** +
+ +
+
+

+hilbish.runner.get(name) + + + +

+ +Get a runner by name. +#### Parameters +`name` **`string`** +
+ +
+
+

+hilbish.runner.set(name, runner) + + + +

+ +Sets a runner by name. The runner table must have the run function in it. +#### Parameters +`name` **`string`** +`runner` **`table`** +
+ +
+
+

+hilbish.runner.exec(cmd, runnerName) + + + +

+ +Executes cmd with a runner. If runnerName isn't passed, it uses +the user's current runner. +#### Parameters +`cmd` **`string`** +`runnerName` **`string?`** +
+ diff --git a/docs/nature/dirs.md b/docs/nature/dirs.md index 3c707e6..2a0e966 100644 --- a/docs/nature/dirs.md +++ b/docs/nature/dirs.md @@ -8,7 +8,7 @@ menu: ---
-
+
-
+
-
+
-
+
-
+

dirs.recent(idx) diff --git a/nature/runner.lua b/nature/runner.lua index 235ab77..0725810 100644 --- a/nature/runner.lua +++ b/nature/runner.lua @@ -1,4 +1,4 @@ ---- hilbish.runner +-- @module hilbish.runner local currentRunner = 'hybrid' local runners = {} From 5545002d9238dc3f18e1dcc8ad575c255947e5b6 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 24 Dec 2024 18:53:34 -0400 Subject: [PATCH 2/3] fix: signature link in table of contents --- cmd/docgen/docgen.lua | 2 +- docs/api/hilbish/hilbish.runner.md | 27 +++++++-------------------- 2 files changed, 8 insertions(+), 21 deletions(-) diff --git a/cmd/docgen/docgen.lua b/cmd/docgen/docgen.lua index 50e777c..7468f3b 100644 --- a/cmd/docgen/docgen.lua +++ b/cmd/docgen/docgen.lua @@ -134,7 +134,7 @@ for iface, dps in pairs(pieces) do if tocPos then local pos = f:seek() f:seek('set', tocPos) - f:write(string.format('||%s|\n', func, docs.description[1])) + f:write(string.format('|%s|%s|\n', func, sig, docs.description[1])) tocPos = f:seek() f:seek('set', pos) end diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 7fb18e9..244fb87 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -57,26 +57,13 @@ end) |setMode(cb)|This is the same as the `hilbish.runnerMode` function.| |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| -||Returns the current runner by name.| -||Sets the current interactive/command line runner mode.| -||Adds a runner to the table of available runners. If runner is a table,| -||Get a runner by name.| -||Sets a runner by name. The runner table must have the run function in it.| -||Executes cmd with a runner. If runnerName isn't passed, it uses| -### Parameters -`function` **`cb`** - - -

- -
-
-

-hilbish.runner.lua(cmd) - - - -

+|hilbish.runner.getCurrent()|Returns the current runner by name.| +|hilbish.runner.setCurrent(name)|Sets the current interactive/command line runner mode.| +|hilbish.runner.add(name, runner)|Adds a runner to the table of available runners. If runner is a table,| +|hilbish.runner.get(name)|Get a runner by name.| +|hilbish.runner.set(name, runner)|Sets a runner by name. The runner table must have the run function in it.| +|hilbish.runner.exec(cmd, runnerName)|Executes cmd with a runner. If runnerName isn't passed, it uses| +> Evaluates `cmd` as Lua input. This is the same as using `dofile` or `load`, but is appropriated for the runner interface. From b7af6177ba436d113e72e23af658e4094f8ee990 Mon Sep 17 00:00:00 2001 From: sammyette Date: Tue, 24 Dec 2024 18:59:32 -0400 Subject: [PATCH 3/3] fix: reduce function list to match in go generated docs --- cmd/docgen/docgen.lua | 11 ++++++++--- docs/api/hilbish/hilbish.runner.md | 18 +++++++++++------- 2 files changed, 19 insertions(+), 10 deletions(-) diff --git a/cmd/docgen/docgen.lua b/cmd/docgen/docgen.lua index 7468f3b..e3d2b5f 100644 --- a/cmd/docgen/docgen.lua +++ b/cmd/docgen/docgen.lua @@ -125,16 +125,21 @@ for iface, dps in pairs(pieces) do for func, docs in pairs(dps) do local sig = string.format('%s.%s(', iface, func) + local params = '' for idx, param in ipairs(docs.params) do - sig = sig .. ((param.name:gsub('%?$', ''))) - if idx ~= #docs.params then sig = sig .. ', ' end + sig = sig .. param.name:gsub('%?$', '') + params = params .. param.name:gsub('%?$', '') + if idx ~= #docs.params then + sig = sig .. ', ' + params = params .. ', ' + end end sig = sig .. ')' if tocPos then local pos = f:seek() f:seek('set', tocPos) - f:write(string.format('|%s|%s|\n', func, sig, docs.description[1])) + f:write(string.format('|%s|%s|\n', func, string.format('%s(%s)', func, params), docs.description[1])) tocPos = f:seek() f:seek('set', pos) end diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 244fb87..303996d 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -57,13 +57,17 @@ end) |setMode(cb)|This is the same as the `hilbish.runnerMode` function.| |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| -|hilbish.runner.getCurrent()|Returns the current runner by name.| -|hilbish.runner.setCurrent(name)|Sets the current interactive/command line runner mode.| -|hilbish.runner.add(name, runner)|Adds a runner to the table of available runners. If runner is a table,| -|hilbish.runner.get(name)|Get a runner by name.| -|hilbish.runner.set(name, runner)|Sets a runner by name. The runner table must have the run function in it.| -|hilbish.runner.exec(cmd, runnerName)|Executes cmd with a runner. If runnerName isn't passed, it uses| -> +|getCurrent()|Returns the current runner by name.| +|setCurrent(name)|Sets the current interactive/command line runner mode.| +|add(name, runner)|Adds a runner to the table of available runners. If runner is a table,| +|get(name)|Get a runner by name.| +|set(name, runner)|Sets a runner by name. The runner table must have the run function in it.| +|exec(cmd, runnerName)|Executes cmd with a runner. If runnerName isn't passed, it uses| +d) + + + +

Evaluates `cmd` as Lua input. This is the same as using `dofile` or `load`, but is appropriated for the runner interface.