From b0e05d4b16cc57440b45bd0c2220023e73be0c46 Mon Sep 17 00:00:00 2001 From: sammyette Date: Mon, 25 Dec 2023 18:50:27 -0400 Subject: [PATCH] feat: add nature module docs --- cmd/docgen/docgen.lua | 94 ++++++++++++++++++++++++++++++++++---- docs/nature/dirs.md | 79 ++++++++++++++++++++++++++++++++ luadocs/api/nature/dirs.md | 0 luadocs/api/nil/dirs.md | 0 nature/dirs.lua | 8 ++-- 5 files changed, 167 insertions(+), 14 deletions(-) create mode 100644 docs/nature/dirs.md delete mode 100644 luadocs/api/nature/dirs.md delete mode 100644 luadocs/api/nil/dirs.md diff --git a/cmd/docgen/docgen.lua b/cmd/docgen/docgen.lua index 88837f9..207357a 100644 --- a/cmd/docgen/docgen.lua +++ b/cmd/docgen/docgen.lua @@ -17,17 +17,53 @@ for _, fname in ipairs(files) do pieces[mod] = {} local docPiece = {} + local lines = {} + local lineno = 0 for line in f:lines() do + lineno = lineno + 1 + lines[lineno] = line + if line == header then goto continue2 end if not line:match(emmyPattern) then if line:match '^function' then local pattern = (string.format('^function %s%%.', mod) .. '(%w+)') local funcName = line:match(pattern) if not funcName then goto continue2 end - print(line) - print(pattern) - print(funcName) - pieces[iface][funcName] = docPiece + + local dps = { + description = {}, + params = {} + } + + local offset = 1 + while true do + local prev = lines[lineno - offset] + + local docline = prev:match '^%-+ (.+)' + if docline then + local emmy = docline:match '@(%w+)' + local cut = 0 + + if emmy then cut = emmy:len() + 3 end + local emmythings = string.split(docline:sub(cut), ' ') + + if emmy then + if emmy == 'param' then + table.insert(dps.params, 1, { + name = emmythings[1], + type = emmythings[2] + }) + end + else + table.insert(dps.description, 1, docline) + end + offset = offset + 1 + else + break + end + end + + pieces[mod][funcName] = dps end docPiece = {} goto continue2 @@ -39,20 +75,57 @@ for _, fname in ipairs(files) do ::continue:: end +local header = [[--- +title: %s %s +description: %s +layout: doc +menu: + docs: + parent: "Nature" +--- + +]] + for iface, dps in pairs(pieces) do local mod = iface:match '(%w+)%.' or 'nature' - local path = string.format('luadocs/api/%s/%s.md', mod, iface) - local f = io.open(path, 'a+') + local path = string.format('docs/%s/%s.md', mod, iface) + fs.mkdir(fs.dir(path), true) + local f = io.open(path, 'w') + f:write(string.format(header, 'Module', iface, 'No description.')) print(f) print(mod, path) - fs.mkdir(fs.dir(path), true) 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([[ +

+%s + + + +

+ +]], sig, func)) + + f:write(table.concat(docs.description, '\n') .. '\n') + f:write '#### Parameters\n' + if #docs.params == 0 then + f:write 'This function has no parameters. \n' + end + for _, param in ipairs(docs.params) do + f:write(string.format('`%s` **`%s`**\n', param.name:gsub('%?$', ''), param.type)) + end + --[[ local params = table.filter(docs, function(t) return t:match '^%-%-%- @param' end) - f:write(string.format('## %s(', func)) for i, str in ipairs(params) do if i ~= 1 then f:write ', ' @@ -66,7 +139,8 @@ for iface, dps in pairs(pieces) do f:write(str:match '^%-%-%- (.+)' .. '\n') end end - f:write('\n') + ]]-- + f:write('
') + f:write('\n\n') end - f:flush() end diff --git a/docs/nature/dirs.md b/docs/nature/dirs.md new file mode 100644 index 0000000..3c707e6 --- /dev/null +++ b/docs/nature/dirs.md @@ -0,0 +1,79 @@ +--- +title: Module dirs +description: No description. +layout: doc +menu: + docs: + parent: "Nature" +--- + +
+
+

+dirs.setOld(d) + + + +

+ +Sets the old directory string. +#### Parameters +`d` **`string`** +
+ +
+
+

+dirs.push() + + + +

+ +Add `d` to the recent directories list. +#### Parameters +This function has no parameters. +
+ +
+
+

+dirs.peak(num) + + + +

+ +Look at `num` amount of recent directories, starting from the latest. +#### Parameters +`num` **`number`** +
+ +
+
+

+dirs.pop(num) + + + +

+ +Remove the specified amount of dirs from the recent directories list. +#### Parameters +`num` **`number`** +
+ +
+
+

+dirs.recent(idx) + + + +

+ +Get entry from recent directories list based on index. +#### Parameters +`idx` **`number`** +
+ diff --git a/luadocs/api/nature/dirs.md b/luadocs/api/nature/dirs.md deleted file mode 100644 index e69de29..0000000 diff --git a/luadocs/api/nil/dirs.md b/luadocs/api/nil/dirs.md deleted file mode 100644 index e69de29..0000000 diff --git a/nature/dirs.lua b/nature/dirs.lua index 5e738b6..328b4b7 100644 --- a/nature/dirs.lua +++ b/nature/dirs.lua @@ -40,7 +40,7 @@ function dirs.peak(num) return dirRecents(num) end ---- Add `d` to the recent directories. +--- Add `d` to the recent directories list. function dirs.push(d) dirs.recentDirs[dirs.recentSize + 1] = nil if dirs.recentDirs[#dirs.recentDirs - 1] ~= d then @@ -51,19 +51,19 @@ function dirs.push(d) end end ---- Remove `num` amount of dirs from the recent directories. +--- Remove the specified amount of dirs from the recent directories list. -- @param num number function dirs.pop(num) return dirRecents(num, true) end ---- Get entry from recent directories. +--- Get entry from recent directories list based on index. -- @param idx number function dirs.recent(idx) return dirs.recentDirs[idx] end ---- Sets the old directory. +--- Sets the old directory string. -- @param d string function dirs.setOld(d) ok, d = pcall(fs.abs, d)