1 -------------------------------------------------------------------------------
2 -- Doclet that generates HTML output. This doclet generates a set of html files
3 -- based on a group of templates. The main templates are:
5 -- <li>index.lp: index of modules and files;</li>
6 -- <li>file.lp: documentation for a lua file;</li>
7 -- <li>module.lp: documentation for a lua module;</li>
8 -- <li>function.lp: documentation for a lua function. This is a
9 -- sub-template used by the others.</li>
12 -- @release $Id: html.lua,v 1.29 2007/12/21 17:50:48 tomas Exp $
13 -------------------------------------------------------------------------------
15 local assert, getfenv, ipairs, loadstring, pairs, setfenv, tostring, tonumber, type = assert, getfenv, ipairs, loadstring, pairs, setfenv, tostring, tonumber, type
16 local io = require"io"
17 local posix = require "posix"
18 local lp = require "luadoc.lp"
19 local luadoc = require"luadoc"
20 local package = package
21 local string = require"string"
22 local table = require"table"
23 local luciutil = require "luci.util"
25 module "luadoc.doclet.html"
27 -------------------------------------------------------------------------------
28 -- Looks for a file `name' in given path. Removed from compat-5.1
29 -- @param path String with the path.
30 -- @param name String with the name to look for.
31 -- @return String with the complete path of the file found
32 -- or nil in case the file is not found.
34 local function search (path, name)
35 for c in string.gfind(path, "[^;]+") do
36 c = string.gsub(c, "%?", name)
38 if f then -- file exist?
43 return nil -- file not found
46 -------------------------------------------------------------------------------
47 -- Include the result of a lp template into the current stream.
49 function include (template, env)
50 -- template_dir is relative to package.path
51 local templatepath = options.template_dir .. template
53 -- search using package.path (modified to search .lp instead of .lua
54 local search_path = string.gsub(package.path, "%.lua", "")
55 local templatepath = search(search_path, templatepath)
56 assert(templatepath, string.format("template `%s' not found", template))
63 env.tonumber = tonumber
64 env.tostring = tostring
69 return lp.include(templatepath, env)
72 -------------------------------------------------------------------------------
73 -- Returns a link to a html file, appending "../" to the link to make it right.
74 -- @param html Name of the html file to link to
75 -- @return link to the html file
77 function link (html, from)
80 string.gsub(from, "/", function () h = "../" .. h end)
84 -------------------------------------------------------------------------------
85 -- Returns the name of the html file to be generated from a module.
86 -- Files with "lua" or "luadoc" extensions are replaced by "html" extension.
87 -- @param modulename Name of the module to be processed, may be a .lua file or
89 -- @return name of the generated html file for the module
91 function module_link (modulename, doc, from)
92 -- TODO: replace "." by "/" to create directories?
93 -- TODO: how to deal with module names with "/"?
98 if doc.modules[modulename] == nil then
99 -- logger:error(string.format("unresolved reference to module `%s'", modulename))
103 local href = "modules/" .. modulename .. ".html"
104 string.gsub(from, "/", function () href = "../" .. href end)
108 -------------------------------------------------------------------------------
109 -- Returns the name of the html file to be generated from a lua(doc) file.
110 -- Files with "lua" or "luadoc" extensions are replaced by "html" extension.
111 -- @param to Name of the file to be processed, may be a .lua file or
113 -- @param from path of where am I, based on this we append ..'s to the
115 -- @return name of the generated html file
117 function file_link (to, from)
122 href = string.gsub(href, "lua$", "html")
123 href = string.gsub(href, "luadoc$", "html")
124 href = "files/" .. href
125 string.gsub(from, "/", function () href = "../" .. href end)
129 -------------------------------------------------------------------------------
130 -- Returns a link to a function or to a table
131 -- @param fname name of the function or table to link to.
132 -- @param doc documentation table
133 -- @param kind String specying the kinf of element to link ("functions" or "tables").
135 function link_to (fname, doc, module_doc, file_doc, from, kind)
139 kind = kind or "functions"
141 --luciutil.dumptable( module_doc )
144 for _, func_name in pairs(file_doc[kind]) do
145 if func_name == fname then
146 return file_link(file_doc.name, from) .. "#" .. fname
151 if module_doc and module_doc[kind] then
152 for func_name, tbl in pairs(module_doc[kind]) do
153 if func_name == fname then
159 local _, _, modulename, fname = string.find(fname, "^(.-)[%.%:]?([^%.%:]*)$")
162 -- if fname does not specify a module, use the module_doc
163 if string.len(modulename) == 0 and module_doc then
164 modulename = module_doc.name
167 local module_doc = doc.modules[modulename]
168 if not module_doc then
169 -- logger:error(string.format("unresolved reference to function `%s': module `%s' not found", fname, modulename))
173 for _, func_name in pairs(module_doc[kind]) do
174 if func_name == fname then
175 return module_link(modulename, doc, from) .. "#" .. fname
179 -- logger:error(string.format("unresolved reference to function `%s' of module `%s'", fname, modulename))
182 -------------------------------------------------------------------------------
183 -- Make a link to a file, module or function
185 function symbol_link (symbol, doc, module_doc, file_doc, from)
190 -- file_link(symbol, from) or
191 module_link(symbol, doc, from) or
192 link_to(symbol, doc, module_doc, file_doc, from, "functions") or
193 link_to(symbol, doc, module_doc, file_doc, from, "tables")
196 logger:error(string.format("unresolved reference to symbol `%s'", symbol))
202 -------------------------------------------------------------------------------
203 -- Assembly the output filename for an input file.
204 -- TODO: change the name of this function
205 function out_file (filename)
207 h = string.gsub(h, "lua$", "html")
208 h = string.gsub(h, "luadoc$", "html")
210 -- h = options.output_dir .. string.gsub (h, "^.-([%w_]+%.html)$", "%1")
211 h = options.output_dir .. h
215 -------------------------------------------------------------------------------
216 -- Assembly the output filename for a module.
217 -- TODO: change the name of this function
218 function out_module (modulename)
219 local h = modulename .. ".html"
221 h = options.output_dir .. h
225 -----------------------------------------------------------------
226 -- Generate the output.
227 -- @param doc Table with the structured documentation.
230 -- Generate index file
231 if (#doc.files > 0 or #doc.modules > 0) and (not options.noindexpage) then
232 local filename = options.output_dir.."index.html"
233 logger:info(string.format("generating file `%s'", filename))
234 local f = posix.open(filename, "w")
235 assert(f, string.format("could not open `%s' for writing", filename))
237 include("index.lp", { doc = doc })
242 if not options.nomodules then
243 for _, modulename in ipairs(doc.modules) do
244 local module_doc = doc.modules[modulename]
245 -- assembly the filename
246 local filename = out_module(modulename)
247 logger:info(string.format("generating file `%s'", filename))
249 local f = posix.open(filename, "w")
250 assert(f, string.format("could not open `%s' for writing", filename))
252 include("module.lp", { doc = doc, module_doc = module_doc })
258 if not options.nofiles then
259 for _, filepath in ipairs(doc.files) do
260 local file_doc = doc.files[filepath]
261 -- assembly the filename
262 local filename = out_file(file_doc.name)
263 logger:info(string.format("generating file `%s'", filename))
265 local f = posix.open(filename, "w")
266 assert(f, string.format("could not open `%s' for writing", filename))
268 include("file.lp", { doc = doc, file_doc = file_doc} )
274 local f = posix.open(options.output_dir.."luadoc.css", "w")
276 include("luadoc.css")