forked from mtcontrib/3d_armor
Add Support for Generating HTML Documentation with LDoc (#58)
* Add Python scripts to generate temp files that can be parsed by LDoc * Add config & script for generating HTML docs with LDoc... * Add Lua docstrings for API & items * Add workflow for building API reference docs on gh-pages branch * Add LDoc's default stylesheet * LDoc: make navigation panel fixed
This commit is contained in:
Jordan Irwin
GitHub
344
.ldoc/config.ld
Normal file
344
.ldoc/config.ld
Normal file
@ -0,0 +1,344 @@
|
||||
-- Place this file in mod "docs" directory
|
||||
|
||||
local print, type, string, table, tostring, tonumber, error, pairs, ipairs
|
||||
if import then
|
||||
print = import("print")
|
||||
type = import("type")
|
||||
string = import("string")
|
||||
table = import("table")
|
||||
tostring = import("tostring")
|
||||
tonumber = import("tonumber")
|
||||
error = import("error")
|
||||
pairs = import("pairs")
|
||||
ipairs = import("ipairs")
|
||||
end
|
||||
|
||||
project = "3d_armor"
|
||||
title = "3D Armor"
|
||||
format = "markdown"
|
||||
not_luadoc = true
|
||||
boilerplate = false
|
||||
wrap = false
|
||||
style = true
|
||||
|
||||
file = {
|
||||
"3d_armor/api.lua",
|
||||
".ldoc/settings.luadoc",
|
||||
--".ldoc/armors.luadoc",
|
||||
".ldoc/helmets.luadoc",
|
||||
".ldoc/chestplates.luadoc",
|
||||
".ldoc/leggings.luadoc",
|
||||
".ldoc/boots.luadoc",
|
||||
".ldoc/shields.luadoc",
|
||||
".ldoc/crafting.luadoc",
|
||||
}
|
||||
|
||||
|
||||
new_type("setting", "Settings")
|
||||
new_type("armor", "Armors")
|
||||
new_type("craft", "Craft Recipes")
|
||||
|
||||
alias("helmet", "armor")
|
||||
alias("chestplate", "armor")
|
||||
alias("leggings", "armor")
|
||||
alias("boots", "armor")
|
||||
alias("shield", "armor")
|
||||
alias("grp", "group")
|
||||
|
||||
-- function declarations
|
||||
local format_text
|
||||
local format_group
|
||||
|
||||
custom_tags = {
|
||||
-- settings
|
||||
{
|
||||
"settype",
|
||||
title = "Type",
|
||||
hidden = true,
|
||||
},
|
||||
{
|
||||
"min",
|
||||
title = "Minimum Value",
|
||||
hidden = true,
|
||||
},
|
||||
{
|
||||
"max",
|
||||
title = "Maximum Value",
|
||||
hidden = true,
|
||||
},
|
||||
{
|
||||
"default",
|
||||
title = "Default Value",
|
||||
hidden = true,
|
||||
},
|
||||
-- craft items/tools
|
||||
{
|
||||
-- specify image basename only
|
||||
"img",
|
||||
title = "Image",
|
||||
format = function(value)
|
||||
local img = "<img src=\"https://raw.githubusercontent.com/minetest-mods/3d_armor/master/"
|
||||
if string then
|
||||
if string.find(value, "shields_") == 1 then
|
||||
img = img .. "shields/"
|
||||
else
|
||||
img = img .. "3d_armor/"
|
||||
end
|
||||
end
|
||||
|
||||
return img .. "textures/" .. value .. "\" style=\"width:32px; height:32px;\" />"
|
||||
end,
|
||||
},
|
||||
{
|
||||
-- specify full (relative or absolute) image path
|
||||
"image",
|
||||
title = "Image",
|
||||
format = function(value)
|
||||
return "<img src=\"" .. value .. "\" style=\"width:32px; height:32px;\" />"
|
||||
end,
|
||||
},
|
||||
{
|
||||
"group",
|
||||
title = "Groups",
|
||||
format = function(value)
|
||||
return format_group(value)
|
||||
end,
|
||||
},
|
||||
{
|
||||
"armorgrp",
|
||||
title = "Armor Groups",
|
||||
format = function(value)
|
||||
return format_group(value)
|
||||
end,
|
||||
},
|
||||
{
|
||||
"damagegrp",
|
||||
title = "Damage Groups",
|
||||
format = function(value)
|
||||
return format_group(value)
|
||||
end,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
if string then
|
||||
string.trim = function(st, delim)
|
||||
if not delim then
|
||||
delim = " "
|
||||
end
|
||||
|
||||
while string.find(st, delim) == 1 do
|
||||
st = st:sub(2)
|
||||
end
|
||||
|
||||
while string.sub(st, string.len(st)) == delim do
|
||||
st = st:sub(1, string.len(st)-1)
|
||||
end
|
||||
|
||||
return st
|
||||
end
|
||||
|
||||
string.split = function(st, delim)
|
||||
local list = {}
|
||||
|
||||
local idx = string.find(st, delim)
|
||||
while idx do
|
||||
table.insert(list, st:sub(1, idx-1))
|
||||
st = st:sub(idx+1)
|
||||
idx = string.find(st, delim)
|
||||
end
|
||||
-- add remaining item
|
||||
table.insert(list, st)
|
||||
|
||||
return list
|
||||
end
|
||||
end
|
||||
|
||||
if table then
|
||||
if not table.copy then
|
||||
table.copy = function(orig_table)
|
||||
local new_table = {}
|
||||
for k, v in pairs(orig_table) do
|
||||
new_table[k] = v
|
||||
end
|
||||
|
||||
return new_table
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
format_text = function(text, flags)
|
||||
local ret = "<"
|
||||
local ttype = "span"
|
||||
if flags.code then
|
||||
ttype = "code"
|
||||
end
|
||||
|
||||
ret = ret .. ttype .. " style=\""
|
||||
|
||||
if flags.size then
|
||||
ret = ret .. "font-size:" .. flags.size .. ";"
|
||||
end
|
||||
if flags.mono then
|
||||
ret = ret .. "font-family:monospace;"
|
||||
end
|
||||
if flags.italic then
|
||||
ret = ret .. "font-style:italic;"
|
||||
end
|
||||
if flags.bold then
|
||||
ret = ret .. "font-weight:bold;"
|
||||
end
|
||||
if flags.color then
|
||||
ret = ret .. "color:" .. flags.color .. ";"
|
||||
end
|
||||
if flags.bgcolor then
|
||||
ret = ret .. "background-color:" .. flags.bgcolor .. ";"
|
||||
end
|
||||
|
||||
ret = ret .. "\">" .. text .. "</" .. ttype .. ">"
|
||||
|
||||
return ret
|
||||
end
|
||||
|
||||
format_group = function(text)
|
||||
if string then
|
||||
local idx, k, v = string.find(text, " ")
|
||||
if idx then
|
||||
text = format_text(string.sub(text, 1, idx-1) .. ": ", {mono=true, color="darkgreen"})
|
||||
.. string.sub(text, idx)
|
||||
end
|
||||
end
|
||||
|
||||
return text
|
||||
end
|
||||
|
||||
|
||||
local function format_setting_tag(desc, value)
|
||||
return "\n- <span style=\"font-size:80%;\">`" .. desc .. ":`</span> `" .. value .. "`"
|
||||
end
|
||||
|
||||
|
||||
local registered = {
|
||||
settings = {},
|
||||
}
|
||||
|
||||
local function setting_handler(item)
|
||||
if not ipairs or not type then
|
||||
return item
|
||||
end
|
||||
|
||||
local tags = {
|
||||
{"settype", "type"},
|
||||
{"default"},
|
||||
{"min", "minimum value"},
|
||||
{"max", "maximum value"},
|
||||
}
|
||||
|
||||
local def = {
|
||||
["settype"] = format_setting_tag("type", "string"),
|
||||
}
|
||||
|
||||
for _, t in ipairs(tags) do
|
||||
local name = t[1]
|
||||
local desc = t[2]
|
||||
if not desc then desc = name end
|
||||
|
||||
local value = item.tags[name]
|
||||
if type(value) == "table" then
|
||||
if #value > 1 then
|
||||
local msg = item.file.filename .. " (line " .. item.lineno
|
||||
.. "): multiple instances of tag \"" .. name .. "\" found"
|
||||
if error then
|
||||
error(msg)
|
||||
elseif print then
|
||||
print("WARNING: " .. msg)
|
||||
end
|
||||
end
|
||||
|
||||
if value[1] then
|
||||
def[name] = format_setting_tag(desc, value[1])
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
item.description = item.description .. "\n\n**Definition:**\n" .. def.settype
|
||||
for _, t in ipairs({def.default, def.min, def.max}) do
|
||||
if t then
|
||||
item.description = item.description .. t
|
||||
end
|
||||
end
|
||||
|
||||
registered.settings[item.name] = true
|
||||
|
||||
return item
|
||||
end
|
||||
|
||||
function custom_display_name_handler(item, default_handler)
|
||||
if item.type == "setting" then
|
||||
-- avoid parsing again
|
||||
if not registered.settings[item.name] then
|
||||
item = setting_handler(item)
|
||||
end
|
||||
elseif item.type == "armor" and string then
|
||||
-- HACK: not sure why "shields:" is being trimmed from item name
|
||||
if string.find(item.name, "shield_") == 1 then
|
||||
item.name = "shields:" .. item.name
|
||||
end
|
||||
end
|
||||
|
||||
if item then
|
||||
return default_handler(item)
|
||||
end
|
||||
end
|
||||
|
||||
|
||||
local custom_see_links = {
|
||||
["ObjectRef"] = "https://minetest.gitlab.io/minetest/class-reference/#objectref",
|
||||
["PlayerMetaRef"] = "https://minetest.gitlab.io/minetest/class-reference/#playermetaref",
|
||||
["ItemDef"] = "https://minetest.gitlab.io/minetest/definition-tables/#item-definition",
|
||||
["ItemStack"] = "https://minetest.gitlab.io/minetest/class-reference/#itemstack",
|
||||
["groups"] = "https://minetest.gitlab.io/minetest/groups/",
|
||||
["entity_damage_mechanism"] = "https://minetest.gitlab.io/minetest/entity-damage-mechanism/",
|
||||
["vector"] = "https://minetest.gitlab.io/minetest/representations-of-simple-things/#positionvector",
|
||||
}
|
||||
|
||||
local function format_custom_see(name, section)
|
||||
local url = custom_see_links[name]
|
||||
if not url then
|
||||
url = ""
|
||||
end
|
||||
|
||||
if not name then
|
||||
name = ""
|
||||
end
|
||||
|
||||
return name, url
|
||||
end
|
||||
|
||||
custom_see_handler("^(ObjectRef)$", function(name, section)
|
||||
return format_custom_see(name, section)
|
||||
end)
|
||||
|
||||
custom_see_handler("^(PlayerMetaRef)$", function(name, section)
|
||||
return format_custom_see(name, section)
|
||||
end)
|
||||
|
||||
custom_see_handler("^(ItemDef)$", function(name, section)
|
||||
return format_custom_see(name, section)
|
||||
end)
|
||||
|
||||
custom_see_handler("^(groups)$", function(name, section)
|
||||
return format_custom_see(name, section)
|
||||
end)
|
||||
|
||||
custom_see_handler("^(entity_damage_mechanism)$", function(name, section)
|
||||
return format_custom_see(name, section)
|
||||
end)
|
||||
|
||||
custom_see_handler("^(ItemStack)$", function(name, section)
|
||||
return format_custom_see(name, section)
|
||||
end)
|
||||
|
||||
custom_see_handler("^(vector)$", function(name, section)
|
||||
return name, "https://minetest.gitlab.io/minetest/representations-of-simple-things/#positionvector"
|
||||
end)
|
||||
Reference in New Issue
Block a user