Reuh/anselme
1
0
Fork 0
mirror of https://github.com/Reuh/anselme.git synced 2025-10-27 16:49:31 +00:00
Code Releases Activity

[doc] update gendocs for Anselme standard library and add title and defer tags

Browse source
This commit is contained in:
Étienne Fildadut 2024-05-28 18:14:10 +02:00
parent a631334b31
commit bdc4f8a13a
5 changed files with 162 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

114
doc/gendocs.lua
View file

@ -5,12 +5,22 @@
local utf8 = utf8 or require("lua-utf8")
local files = {
"doc/api.md"
"doc/api.md",
"doc/standard_library.md"
}
local source_link_prefix = "../"
local base_header_level = 2
local function unescape(str)
return str:gsub("\\(.)", "%1")
end
local title_extractors = {
-- anselme luafunction definition
{ "\"(.-)\",%s*\"(.-)\",", function(name, params)
return ("%s %s"):format(unescape(name), unescape(params))
end },
-- methods
{ "(.-)%s*=%s*function%s*%(%s*self%s*%)", ":%1 ()" },
{ "(.-)%s*=%s*function%s*%(%s*self%s*%,%s*(.-)%)", ":%1 (%2)" },
@ -32,44 +42,78 @@ local function extract_block_title(line)
return title
end
local valid_tags = { title = true, defer = true }
local function process(content)
local deferred = {}
return content:gsub("{{(.-)}}", function(lua_file)
local f = io.open(lua_file, "r")
local c = f:read("a")
f:close()
local output = {}
local comment_block
local line_no = 1
for line in c:gmatch("[^\n]*") do
if line:match("^%s*%-%-%-") then
comment_block = {}
table.insert(comment_block, (line:match("^%s*%-%-%-%s?(.-)$")))
elseif comment_block then
if line:match("^%s*%-%-") then
table.insert(comment_block, (line:match("^%s*%-%-%s?(.-)$")))
else
if line:match("[^%s]") then
local ident, code = line:match("^(%s*)(.-)$")
table.insert(comment_block, 1, ("%s %s\n"):format(
("#"):rep(base_header_level+utf8.len(ident)),
extract_block_title(code)
))
table.insert(comment_block, ("\n_defined at line %s of [%s](%s):_ `%s`"):format(line_no, lua_file, source_link_prefix..lua_file, code))
end
table.insert(comment_block, "")
table.insert(output, table.concat(comment_block, "\n"))
comment_block = nil
end
-- deferred doc comments
if lua_file:match("^:") then
local defer = lua_file:match("^:(.-)$")
if deferred[defer] then
local output = table.concat(deferred[defer], "\n")
deferred[defer] = nil
return output
else
return ""
end
line_no = line_no + 1
-- lua file
else
local f = io.open(lua_file, "r")
local c = f:read("a")
f:close()
local output = {}
local comment_block
local line_no = 1
for line in c:gmatch("[^\n]*") do
-- doc comment start
if line:match("^%s*%-%-%-") then
comment_block = {}
table.insert(comment_block, (line:match("^%s*%-%-%-%s?(.-)$")))
elseif comment_block then
-- continue doc comment
if line:match("^%s*%-%-") then
local comment = line:match("^%s*%-%-%s?(.-)$")
if comment:match("^%s*@") then
local tag, data = comment:match("^%s*@%s*([^%s]*)%s*(.-)$")
if valid_tags[tag] then comment_block[tag] = data
else print(("unknown documentation tag @%s, at %s:%s"):format(tag, lua_file, line_no)) end
else
table.insert(comment_block, comment)
end
-- end doc comment
else
if line:match("[^%s]") then
local indent, code = line:match("^(%s*)(.-)$")
if not comment_block.indent then comment_block.indent = utf8.len(indent) end
if not comment_block.title then comment_block.title = extract_block_title(code) end
table.insert(comment_block, ("\n_defined at line %s of [%s](%s):_ `%s`"):format(line_no, lua_file, source_link_prefix..lua_file, code))
end
if comment_block.title then
table.insert(comment_block, 1, ("%s %s\n"):format(
("#"):rep(base_header_level+(comment_block.indent or 0)),
comment_block.title
))
end
table.insert(comment_block, "")
local doc_block = table.concat(comment_block, "\n")
if comment_block.defer then
if not deferred[comment_block.defer] then deferred[comment_block.defer] = {} end
table.insert(deferred[comment_block.defer], doc_block)
else
table.insert(output, doc_block)
end
comment_block = nil
end
end
line_no = line_no + 1
end
return table.concat(output, "\n")
end
table.insert(output, ("\n---\n_file generated at %s_"):format(os.date("!%Y-%m-%dT%H:%M:%SZ")))
return table.concat(output, "\n")
end)
end) .. ("\n---\n_file generated at %s_"):format(os.date("!%Y-%m-%dT%H:%M:%SZ"))
end
local function generate_file(input, output)