GitHub/Basalt2
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Docs Parser fixes

Browse Source
This commit is contained in:
Robert Jelic
2025-09-13 22:28:10 +02:00
parent b5f9ced023
commit fc44bc4d8b
4 changed files with 57 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/elements/Tree.lua
View File

@@ -2,6 +2,7 @@ local VisualElement = require("elements/VisualElement")
local sub = string.sub
---@cofnigDescription The tree element provides a hierarchical view of nodes that can be expanded and collapsed, with support for selection and scrolling.
--- This is the tree class. It provides a hierarchical view of nodes that can be expanded and collapsed,
--- with support for selection and scrolling.
---@class Tree : VisualElement

42
tools/BasaltDoc/init.lua
View File

@@ -4,22 +4,26 @@ local defaultPath = package.path
if fs then
local args = {...}
local docsPath = fs.getDir(args[2])
local format = "path;/path/?.lua;/path/?/init.lua;"
local format = "path/?.lua;path/?/init.lua;"
local main = format:gsub("path", docsPath)
package.path = main.."rom/?;"..defaultPath
else
local format = "path/?.lua;path/?/init.lua;"
local main = format:gsub("path", "tools/BasaltDoc")
package.path = main .. ";" .. defaultPath
end
local ok1, classParser = pcall(require, "parsers.classParser")
local classParser = require("parsers.classParser")
local ok2, functionParser = pcall(require, "parsers.functionParser")
local functionParser = require("parsers.functionParser")
local ok3, propertyParser = pcall(require, "parsers.propertyParser")
local propertyParser = require("parsers.propertyParser")
local ok4, eventParser = pcall(require, "parsers.eventParser")
local eventParser = require("parsers.eventParser")
local ok6, globalParser = pcall(require, "parsers.globalParser")
local globalParser = require("parsers.globalParser")
local ok5, markdownGenerator = pcall(require, "utils.markdownGenerator")
local markdownGenerator = require("utils.markdownGenerator")
BasaltDoc.annotationHandlers = {}
@@ -141,11 +145,11 @@ BasaltDoc.registerAnnotation("@globalDescription", function(target, args)
end
end)
if ok1 then classParser.setHandlers(BasaltDoc.annotationHandlers) end
if ok2 then functionParser.setHandlers(BasaltDoc.annotationHandlers) end
if ok3 then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end
if ok4 then eventParser.setHandlers(BasaltDoc.annotationHandlers) end
if ok6 then globalParser.setHandlers(BasaltDoc.annotationHandlers) end
if classParser then classParser.setHandlers(BasaltDoc.annotationHandlers) end
if functionParser then functionParser.setHandlers(BasaltDoc.annotationHandlers) end
if propertyParser then propertyParser.setHandlers(BasaltDoc.annotationHandlers) end
if eventParser then eventParser.setHandlers(BasaltDoc.annotationHandlers) end
if globalParser then globalParser.setHandlers(BasaltDoc.annotationHandlers) end
----------------------------------------------------------------
-- Main Parser
@@ -174,7 +178,7 @@ function BasaltDoc.parse(content)
if i <= #rawLines and rawLines[i]:match("%]%]") then
i = i + 1
end
if #globalAnnotations > 0 and ok6 then
if #globalAnnotations > 0 and globalParser then
local global = globalParser.parse(globalAnnotations, table.concat(globalAnnotations, "\n"))
ast.global = global
end
@@ -211,25 +215,25 @@ function BasaltDoc.parse(content)
elseif #annotationBuffer > 0 then
local nextLine = lines[i]
local skip = false
if nextLine and nextLine:match("^function") and currentClass and ok2 then
if nextLine and nextLine:match("^function") and currentClass and functionParser then
local fn = functionParser.parse(annotationBuffer, nextLine)
if fn then
table.insert(currentClass.functions, fn)
end
skip = true
elseif firstTag then
if firstTag == "@class" and ok1 then
if firstTag == "@class" and classParser then
local class = classParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
if class and not class.skip then
table.insert(ast.classes, class)
currentClass = class
end
elseif firstTag == "@property" and currentClass and ok3 then
elseif firstTag == "@property" and currentClass and propertyParser then
local prop = propertyParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
if prop then
table.insert(currentClass.properties, prop)
end
elseif firstTag == "@event" and currentClass and ok4 then
elseif firstTag == "@event" and currentClass and eventParser then
local evt = eventParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
if evt then
table.insert(currentClass.events, evt)
@@ -246,7 +250,7 @@ function BasaltDoc.parse(content)
end
if #annotationBuffer > 0 and firstTag then
if firstTag == "@class" and ok1 then
if firstTag == "@class" and classParser then
local class = classParser.parse(annotationBuffer, table.concat(annotationBuffer, "\n"))
if class and not class.skip then
table.insert(ast.classes, class)
@@ -259,7 +263,7 @@ function BasaltDoc.parse(content)
end
function BasaltDoc.generateMarkdown(ast)
if ok5 then
if markdownGenerator then
local result = markdownGenerator.generate(ast)
return result
else

23
tools/BasaltDoc/parsers/functionParser.lua
View File

@@ -2,14 +2,14 @@ local helper = require("utils.helper")
local functionParser = {}
function functionParser.parse(annotations, line)
local name = line:match("^function%s+([%w_%.]+[:.]?[%w_]+)") or line:match("^function%s+([%w_]+)")
if not name then
local funcName = line:match("function ([%w_%.]+:?[%w_]*)")
if not funcName then
print("Warning: Could not extract function name from line: " .. line)
return nil
end
local f = {
type = "function",
name = name,
name = funcName,
description = nil,
shortDescription = nil,
params = {},
@@ -21,17 +21,14 @@ function functionParser.parse(annotations, line)
helper.applyAnnotations(annotations, f, functionParser.handlers)
end
local funcName = line:match("function ([%w_%.]+)")
if funcName then
if funcName:find(":") then
f.name = funcName:match(":([%w_]+)")
elseif funcName:find("%.") then
f.name = funcName:match("%.([%w_]+)")
else
f.name = funcName
end
if funcName:find(":") then
f.name = funcName:match(":([%w_]+)")
elseif funcName:find("%.") then
f.name = funcName:match("%.([%w_]+)")
else
f.name = funcName
end
if line:match("function [%w_%.]+:") then
f.static = false
else

53
tools/generate-docs.lua
View File

@@ -1,6 +1,3 @@
-- generate-docs.lua
-- Argumente
local arg = arg or {...}
local SRC_DIR = arg[1] or "src"
local OUT_DIR = arg[2] or "build_docs/docs/references"
@@ -9,10 +6,6 @@ package.path = package.path .. ";./tools/?.lua"
local BasaltDoc = require("tools/BasaltDoc")
--------------------------------------------------------
-- Filesystem Abstraction
--------------------------------------------------------
local fileSystem
if fs then
@@ -25,7 +18,9 @@ if fs then
open = function(path, mode) return fs.open(path, mode) end,
getDir = fs.getDir,
readAll = function(file) return file.readAll() end,
write = function(file, data) file.write(data) end,
write = function(file, data)
file.write(data)
end,
close = function(file) file.close() end
}
else
@@ -90,52 +85,35 @@ else
}
end
--------------------------------------------------------
-- Main
--------------------------------------------------------
print("Starting documentation generation...")
print("Source directory: " .. SRC_DIR)
print("Output directory: " .. OUT_DIR)
if not fileSystem.exists(OUT_DIR) then
print("Output directory does not exist, creating it...")
fileSystem.makeDir(OUT_DIR)
else
print("Output directory already exists")
end
local function getLuaFiles(dir)
print("Scanning directory: " .. dir)
if not fileSystem.exists(dir) then
print("Directory does not exist: " .. dir)
return {}
end
local files = {}
local list = fileSystem.list(dir)
print("Found " .. #list .. " items in " .. dir)
for _, item in ipairs(list) do
local path = fileSystem.combine(dir, item)
if fileSystem.isDir(path) then
print(" -> Directory, scanning recursively: " .. path)
local subFiles = getLuaFiles(path)
for _, subFile in ipairs(subFiles) do
table.insert(files, subFile)
end
elseif item:match("%.lua$") then
print(" -> Lua file found: " .. path)
table.insert(files, path)
else
print(" -> Skipping: " .. item)
end
end
return files
end
local luaFiles = getLuaFiles(SRC_DIR)
print("Found " .. #luaFiles .. " Lua files to process")
for _, filePath in ipairs(luaFiles) do
local file = fileSystem.open(filePath, "r")
@@ -143,12 +121,17 @@ for _, filePath in ipairs(luaFiles) do
local content = fileSystem.readAll(file)
fileSystem.close(file)
local ast = BasaltDoc.parse(content)
local markdown = BasaltDoc.generateMarkdown(ast)
if not content or #content == 0 then
print("Warning: Empty file:", filePath)
end
local relativePath = filePath:gsub("^" .. SRC_DIR .. "/", ""):gsub("%.lua$", ".md")
local relativePath = filePath:gsub("^" .. SRC_DIR .. "/?", ""):gsub("%.lua$", ".md")
local outPath = fileSystem.combine(OUT_DIR, relativePath)
local ast = BasaltDoc.parse(content)
local markdown = BasaltDoc.generateMarkdown(ast)
local outDir = fileSystem.getDir(outPath)
if outDir and outDir ~= "" and not fileSystem.exists(outDir) then
fileSystem.makeDir(outDir)
@@ -156,15 +139,25 @@ for _, filePath in ipairs(luaFiles) do
local outFile = fileSystem.open(outPath, "w")
if outFile then
fileSystem.write(outFile, table.concat(markdown, "\n"))
if not markdown or (type(markdown) == "table" and #markdown == 0) or (type(markdown) == "string" and #markdown == 0) then
print("Warning: Empty markdown for", filePath)
fileSystem.write(outFile, "!! EMPTY MARKDOWN GENERATED !!\n")
else
if type(markdown) == "table" then
fileSystem.write(outFile, table.concat(markdown, "\n"))
else
fileSystem.write(outFile, tostring(markdown))
end
end
fileSystem.close(outFile)
print("Generated: " .. outPath)
else
print("Error writing: " .. outPath)
end
else
print("Error reading: " .. filePath)
end
end
print("Documentation generation complete.")
print("Documentation generation complete.")