-- Creates a single html that describes the Lua API. Run this thing from
-- within Octane. It creates a single html file with all the docs.
--
-- @description creates html documentation from the Lua API
-- @author Thomas Loockx
-- @version 0.11
-- @shortcut alt + d
-- show the user a file chooser
result = octane.gui.showDialog
{
type = octane.gui.dialogType.FILE_DIALOG,
title = "Choose Lua API html doc output",
wildcards = "*.html;*.htm",
save = true
}
-- append
-- try to open the file and show an error dialog if it failed
doc, errMsg = io.open(result.result, "w")
if not doc then
result = octane.gui.showDialog
{
type = octane.gui.dialogType.ERROR_DIALOG,
title = "File error",
text = errMsg
}
-- stop the script
error(errMsg)
end
local cssStyle =
[[
body
{
font-family: 'Titillium Web', Verdana, Helvetica, sans-serif;
}
h1
{
color: #d50708;
}
h2
{
color: #d50708;
border-bottom: 1px solid #d50708;
}
h3
{
color: #3083aa;
border-bottom: 1px solid #3083aa;
}
a
{
color: #FF6600;
}
a:hover
{
color: white;
background-color: #FF6600;
}
table.funcdoc
{
padding-top: 10px;
}
table.funcdoc th
{
color:#4b6a7e;
padding-right: 40px;
}
]]
local function inArray(array, value)
for _, val in ipairs(array) do
if value == val then return true end
end
return false
end
-- Inline CSS style
doc:write("")
doc:write("")
doc:write(string.format("", cssStyle))
doc:write("")
doc:write("")
-- Logo
doc:write('')
doc:write('
')
doc:write('
')
doc:write('
Lua API (Version %s)", version))
-- get a list with all available modules
local modules = octane.help.modules()
-- HACK: filter out the benchmark module coz it's special
local copy = {}
for module, description in pairs(modules) do
if module ~= "benchmark" then
copy[module] = description
end
end
modules = copy
-- Module overview.
doc:write("Modules Overview
")
doc:write("
")
for name, description in pairs(modules) do
doc:write(string.format("| %s | %s |
", name, name, description))
end
doc:write("
")
-- Per Module breakdown.
for moduleName, description in pairs(modules) do
doc:write(string.format("Module %s
", moduleName, moduleName))
doc:write(string.format("%s
", description))
-- Table with functions.
local modfunctions = octane.help.functions(moduleName)
doc:write("Functions
")
doc:write("")
for _, func in ipairs(modfunctions) do
local funcdoc = octane.help.functionDoc(octane[moduleName][func])
local fullName = string.format("octane.%s.%s", moduleName, func)
doc:write(string.format("| %s | %s |
", fullName, fullName, funcdoc.description))
end
doc:write("
")
-- Table with the properties.
local moduleProps = octane.help.properties(moduleName)
if #moduleProps > 0 then
doc:write("Properties
")
doc:write("")
for idx, propsName in ipairs(moduleProps) do
local propsDoc = octane.help.propertiesDoc(moduleName, propsName)
local fullName = string.format("octane.%s.%s", moduleName, propsName)
doc:write(string.format("| %s | %s |
", fullName, fullName, propsDoc.description))
end
doc:write("
")
end
-- Table with the constants.
local moduleConstants = octane.help.constants(moduleName)
if #moduleConstants > 0 then
doc:write("Constants
")
doc:write("")
for idx, constantName in ipairs(moduleConstants) do
local constantInfo = octane.help.constantDoc(moduleName, constantName)
local fullName = string.format("octane.%s.%s", moduleName, constantName)
doc:write(string.format("| %s | %s |
", fullName, fullName, constantInfo.description))
end
doc:write("
")
end
end
-- Give a breakdown per function.
doc:write("Function Overview
")
for moduleName, moduleDescription in pairs(modules) do
local moduleFunctions = octane.help.functions(moduleName)
for _, functionName in ipairs(moduleFunctions) do
local fullName = string.format("octane.%s.%s", moduleName, functionName)
doc:write(string.format("%s
", fullName, fullName))
local funcDoc = octane.help.functionDoc(octane[moduleName][functionName])
local modProps = octane.help.properties(moduleName)
doc:write("")
-- Table with the description.
doc:write("")
doc:write("| Description |
|---|
")
doc:write(string.format("| %s |
", funcDoc.description))
doc:write("
")
-- Table with the parameters.
if #funcDoc.params > 0 then
doc:write("")
doc:write(" | Parameters |
")
doc:write(" | Name | Type | Description |
")
for _, param in ipairs(funcDoc.params) do
if (not inArray(modProps, param.name)) then
-- regular param
doc:write(string.format(" | %s | %s | %s |
",
param["name"], param["type"], param["description"]))
else
-- property
doc:write(string.format(" | %s | %s | %s |
",
string.format("octane.%s.%s", moduleName, param.name),
param["name"],
param["type"],
param["description"]))
end
end
doc:write("
")
end
-- Table with return values.
if #funcDoc.returns > 0 then
doc:write("")
doc:write(" | Return Values |
")
doc:write(" | Name | Type | Description |
")
for _, ret in ipairs(funcDoc.returns) do
if not inArray(modProps, ret.name) then
-- regular return value.
doc:write(string.format(" | %s | %s | %s |
", ret["name"], ret["type"], ret["description"]))
else
-- property return value.
doc:write(string.format(" | %s | %s | %s |
",
string.format("octane.%s.%s", moduleName, ret.name),
ret["name"],
ret["type"],
ret["description"]))
end
end
doc:write("
")
end
-- Create the synopsis.
local synopsis = ""
if #funcDoc.returns > 0 then
for i=1,#funcDoc.returns-1 do
synopsis = synopsis..funcDoc.returns[i].name..", "
end
synopsis = synopsis..funcDoc.returns[#funcDoc.returns].name.." = "
end
synopsis = synopsis..fullName.."( "
if #funcDoc.params > 0 then
for i=1,#funcDoc.params-1 do
synopsis = synopsis..funcDoc.params[i].name..", "
end
synopsis = synopsis..funcDoc.params[#funcDoc.params].name
end
synopsis = synopsis.." )"
-- Table with the synopsis.
doc:write("")
doc:write("| Synopsis |
|---|
")
doc:write(string.format("| %s |
", synopsis))
doc:write("
")
doc:write("")
end
end
-- Give a breakdown per constant.
doc:write("Constant Overview
")
for moduleName, moduleDescription in pairs(modules) do
local constantNames = octane.help.constants(moduleName)
for _, constantName in ipairs(constantNames) do
local fullName = string.format("octane.%s.%s", moduleName, constantName)
doc:write(string.format("%s
", fullName, fullName))
local constDoc = octane.help.constantDoc(moduleName, constantName)
-- Table with the description.
doc:write("")
doc:write("| Description |
|---|
")
doc:write(string.format("| %s |
", constDoc.description))
doc:write("
")
-- Table with the constant values.
doc:write("")
doc:write("| Values |
|---|
")
-- Get the names.
local names = {}
for name, _ in pairs(constDoc.values) do
table.insert(names, name)
end
-- Sort the names.
table.sort(names)
for _, name in ipairs(names) do
doc:write(string.format(" | %s |
", name))
end
doc:write("
")
end
end
-- Give a breakdown per properties.
doc:write("Properties Overview
")
for moduleName, moduleDescription in pairs(modules) do
local moduleProps = octane.help.properties(moduleName)
for _, propertiesName in ipairs(moduleProps) do
local fullName = string.format("octane.%s.%s", moduleName, propertiesName)
doc:write(string.format("%s
", fullName, fullName))
local propertiesDoc = octane.help.propertiesDoc(moduleName, propertiesName)
doc:write("")
-- Table with the description.
doc:write("")
doc:write("| Description |
|---|
")
doc:write(string.format("| %s |
", propertiesDoc.description))
doc:write("
")
local properties = propertiesDoc.properties
local propNames = {}
for name, _ in pairs(properties) do
table.insert(propNames, name)
end
table.sort(propNames)
-- Table with each proprty
doc:write("")
doc:write(" | Properties |
")
doc:write(" | Name | Description | Type | Writable |
")
for _,name in ipairs(propNames) do
local info = properties[name]
doc:write(string.format(" | %s | %s | %s | %s |
",
name, info.description, info["type"], info.writable))
end
doc:write("
")
doc:write("")
end
end
doc:write("")
doc:write("")