-- eLua doc builder tool
-- List here all the sections for which we're generating the documentation
local doc_sections = { "arch_platform", "refman_gen" }
-- List here all the components of each section
local components =
{
arch_platform = { "ll", "pio", "spi", "uart", "timers", "pwm", "cpu", "eth", "adc" },
refman_gen = { "bit", "pd", "pack", "tmr", "pwm", "cpu", "adc" }
}
-- List here all languages for the documentation (make sure to keep English ("en") the first one)
local languages = { "en", "pt" }
-- Also list here the translation for a bunch of fixed strings
local overview_tr = { en = "Overview", pt = "##Overview" }
local structures_tr = { en = "Data structures", pt = "##Data structures" }
local functions_tr = { en = "Functions", pt = "##Functions" }
-- Format a name to a link by changing all the spaces to "_" and
-- making all letters lowercase
local function name2link( str )
str = str:gsub( " ", "_" )
return str:lower()
end
-- Returns the part of the string enclosed between two '#' chars
-- Used for parsing function sig.
local function namefromsig( str )
local _, _, name = str:find( "#(.*)#" )
return name
end
--[[ Process the given string as follows:
- $string$ becomes string
- %string% becomes string
- @ref@text@ becomes text
- ^ref^text^ becomes text
- $$, %%, @@, ^^ become $, %, @, ^ respectively
- the string "eLua" becomes eLua
- strings between two tildas (~~) get special code-like formatting
- newlines are changed to ' ' if 'keepnl' isn't true
- '&' is translated to its corresponding HTML code.
- '<<' and '>>" are also translated to the corresponding HTML codes (note the repetition).
--]]
local function format_string( str, keepnl )
-- replace double "special chars" with "temps" for later use
str = str:gsub( "%$%$", "\001" )
str = str:gsub( "%%%%", "\002" )
str = str:gsub( "@@", "\003" )
str = str:gsub( "%^%^", "\004" )
str = str:gsub( "~~", "\005" )
-- Translate 'special' HTML chars to their equivalents
local tr_table =
{
[ "%&" ] = "&",
}
for char, rep in pairs( tr_table ) do
str = str:gsub( char, rep )
end
-- some double chars are replaced directly with their HTML codes
str = str:gsub( "<<", "<" )
str = str:gsub( ">>", ">" )
-- replace eLua with eLua
str = str:gsub( "eLua", "eLua" )
-- $string$ becomes string>
str = str:gsub( "%$([^%s%$][^%$]*)%$", "%1" )
-- %string% becomes string
str = str:gsub( "%%([^%s%%][^%%]*)%%", "%1" )
-- @ref@text@ becomes text
str = str:gsub( "@([^%s@][^@]*)@([^%s@][^@]*)@", '%2' )
-- ^ref^text^ becomes text
str = str:gsub( "%^([^%s%^][^%^]*)%^([^%s%^][^%^]*)%^", '%2' )
-- strings between two tildas (~~) get special code-like formatting
str = str:gsub( "~([^%s~][^~]*)~", function( x )
x = x:gsub( "\n", " " )
x = x:gsub( "%s%s+", function( x ) return ( " " ):rep( #x ) end )
return "
" .. x .. "
"
end )
str = str:gsub( "~~", "~" )
-- other "\n" chars should dissapear now
if not keepnl then str = str:gsub( "\n", " " ) end
-- put back the "temps"
str = str:gsub( "\001", "%$" )
str = str:gsub( "\002", "%%" )
str = str:gsub( "\003", "@" )
str = str:gsub( "\004", "%^" )
str = str:gsub( "\005", "~" )
-- all done
return str
end
local header = [[
%s
]]
-- Build the documentation starting from the given file
local function build_file( fname )
dofile( fname )
local res = {}
for _, lang in pairs( languages ) do
res[ lang ] = {}
res[ lang ].wb = {}
local wb = res[ lang ].wb
-- we need english always
-- the other languages will be substituted with english if not found
local resname = string.format( "data_%s", lang )
local r = _G[ resname ]
if not r then
if lang == "en" then
return false, "data_en must exist in the description"
else
print( string.format( "'%s': data for language '%s' not found, defaulting to english", fname, lang ) )
r = _G[ "data_en" ]
end
end
-- process names
if not r.menu_name then
return false, "menu_names not found"
end
wb.name = r.menu_name
-- process title
if not r.title then
return false, "title not found"
end
local page = header:format( r.title ) .. "\n\n"
-- process overview
if not r.overview then
return false, "overview not found"
end
page = page .. '
\n'
for i = 1, #structures do
local s = structures[ i ]
wb.structs[ #wb.structs + 1 ] = s.name
if not s.text or not s.desc or not s.name then
return false, "structure without text, desc or name fields"
end
-- text/name. The link name is ALWAYS the one in ENGLISH.
page = page .. string.format( '', name2link( res.en.wb.structs[ i ] ) )
page = page .. "
\n'
wb.funcs = {}
for i = 1, #funcs do
local f = funcs[ i ]
if not f.sig or not f.desc then
return false, "function without sig or desc fields"
end
local funcname = namefromsig( f.sig )
if not funcname then
return false, string.format( "'%s' should contain the function name between '*' chars", f.sig )
end
wb.funcs[ #wb.funcs + 1 ] = funcname
-- signature
page = page .. string.format( '', funcname )
page = page .. "
Arguments: "
if f.args then
local a = f.args
if type( a ) == "string" or ( type( a ) == "table" and #a == 1 ) then
local text = type( a ) == "string" and a or a[ 1 ]
page = page .. format_string( text )
else
page = page .. "\n
\n"
for i = 1, #a do page = page .. "
" .. format_string( a[ i ] ) .. "
\n" end
page = page .. "
"
end
else
page = page .. "none"
end
page = page .. "\n"
-- return value
page = page .. "
Returns: "
if f.ret then
local r = f.ret
if type( r ) == "string" or ( type( r ) == "table" and #r == 1 ) then
local text = type( r ) == "string" and r or r[ 1 ]
page = page .. format_string( text )
else
page = page .. "\n
\n"
for i = 1, #r do page = page .. "
" .. format_string( r[ i ] ) .. "
\n" end
page = page .. "
"
end
else
page = page .. "nothing"
end
page = page .. "\n\n"
end
-- aux data (if any)
if r.auxdata then
local auxdata = r.auxdata
wb.auxdata = {}
for i = 1, #auxdata do
local a = auxdata[ i ]
wb.auxdata[ #wb.auxdata + 1 ] = a.title
if not a.title or not a.desc then
return false, "auxdata without title or desc"
end
-- the link name is ALWAYS the one in ENGLISH
page = page .. string.format( '', name2link( res.en.wb.auxdata[ i ] ) )
page = page .. "
\n\n"
end
end
-- footer
page = page .. "\n"
res[ lang ].page = page
end
return res
end
-- Helper function to get strings in all languages when needed
local function alllangs( getstr )
local str = "name = {"
for _, lang in pairs( languages ) do
str = str .. string.format( ' %s = "%s",', lang, getstr( lang ) )
end
return str .. " }"
end
-- Transform the data from the wb dictionary (in 'fulldata') for module 'modname' to a wb string, for section 'sect'
local function wb2str( fulldata, modname, sect )
local relfname = sect .. "_" .. modname .. ".html"
local res = fulldata[ modname ]
local wbstr = string.format( ' { %s,\n link = "%s",\n folder =\n {\n', alllangs( function( x ) return res[ x ].wb.name end ), relfname )
-- Overview
wbstr = wbstr .. string.format( ' { %s,\n link = "%s#overview"\n },\n', alllangs( function( x ) return overview_tr[ x ] end ), relfname )
-- Data structures (if needed)
if res.en.wb.structs then
wbstr = wbstr .. string.format( ' { %s,\n link = "%s#structures",\n folder =\n {\n', alllangs( function( x ) return structures_tr[ x ] end ), relfname )
for i = 1, #res.en.wb.structs do
local v = res.en.wb.structs[ i ]
wbstr = wbstr .. string.format( ' { %s,\n link = "%s#%s",\n },\n', alllangs( function( x ) return res[ x ].wb.structs[ i ] end ), relfname, name2link( v ) )
end
wbstr = wbstr .. " }\n },\n"
end
-- Functions
wbstr = wbstr .. string.format( ' { %s,\n link = "%s#funcs",\n folder =\n {\n', alllangs( function( x ) return functions_tr[ x ] end ), relfname )
for _, v in pairs( res.en.wb.funcs ) do
wbstr = wbstr .. string.format( ' { name = { en = "%s", pt = "%s" },\n link = "%s#%s",\n },\n', v, v, relfname, name2link( v ) )
end
wbstr = wbstr .. " }\n },\n"
-- Aux data (if needed)
if res.en.wb.auxdata then
for i = 1, #res.en.wb.auxdata do
local v = res.en.wb.auxdata[ i ]
wbstr = wbstr .. string.format( ' { %s,\n link = "%s#%s"\n },\n', alllangs( function( x ) return res[ x ].wb.auxdata[ i ] end ), relfname, name2link( v ) )
end
end
-- Close the structure and return
wbstr = wbstr .. " }\n },\n"
return wbstr
end
-- Read our complete template for wb_usr.lua
local wbloc = "wb/wb_usr_template.lua"
local realwbloc = "wb/wb_usr.lua"
local wbf = io.open( wbloc, "rb" )
if not wbf then
print( string.format( "Cannot open %s for reading", wbloc ) )
return 1
end
local wbdata = wbf:read( "*a" )
wbf:close()
-- Open the actual wb_usr.lua in write mode
local realwbf = io.open( realwbloc, "wb" )
if not realwbf then
print( string.format( "Cannot open %s for writing", realwbloc ) )
return 1
end
-- Generate documentation for each section in part
for _, section in pairs( doc_sections ) do
-- Check for pattern in wb_usr_template.lua
local pattern = "%$%$" .. section:upper() .. "%$%$"
if not wbdata:find( pattern ) then
print( string.format( "$$%s$$ not found in wb_usr_template.lua", section:upper(), modname ) )
return 1
end
-- Generate documentation for each module in turn
local fulldata = {}
for _, modname in pairs( components[ section ] ) do
local descfname = string.format( "luadoc/%s_%s.lua", section, modname )
local res, err = build_file( descfname )
if res then
fulldata[ modname ] = res
-- Write doc for each language
for _, lang in pairs( languages ) do
local fname = string.format( "%s/%s_%s.html", lang, section, modname )
local f = io.open( fname, "wb" )
if not f then
print( string.format( "Unable to open %s for writing", fname ) )
return 1
else
f:write( res[ lang ].page )
f:close()
print( ( "Wrote %s" ):format( fname ) )
end
end
else
print( string.format( "Error processing module '%s': %s", modname, err ) )
return 1
end
print ""
end
-- Now it's finally time to get our wb/wb_usr.lua
local fullwb = ''
for _, modname in pairs( components[ section ] ) do
local wbstr = wb2str( fulldata, modname, section )
fullwb = fullwb .. wbstr
end
-- Substitute our pattern and write everything back to disk
wbdata = wbdata:gsub( pattern, fullwb )
end
-- Write wb_usr.lua to disk (finally)
realwbf:write( wbdata )
realwbf:close()
print "All done, remember to run 'lua wb_build.lua' in the 'wb' directory to build your navigation tree"