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 "nixio.fs"
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"
24 module "luadoc.doclet.html"
26 -------------------------------------------------------------------------------
27 -- Looks for a file `name' in given path. Removed from compat-5.1
28 -- @param path String with the path.
29 -- @param name String with the name to look for.
30 -- @return String with the complete path of the file found
31 -- or nil in case the file is not found.
33 local function search (path, name)
34 for c in string.gfind(path, "[^;]+") do
35 c = string.gsub(c, "%?", name)
37 if f then -- file exist?
42 return nil -- file not found
45 -------------------------------------------------------------------------------
46 -- Include the result of a lp template into the current stream.
48 function include (template, env)
49 -- template_dir is relative to package.path
50 local templatepath = options.template_dir .. template
52 -- search using package.path (modified to search .lp instead of .lua
53 local search_path = string.gsub(package.path, "%.lua", "")
54 local templatepath = search(search_path, templatepath)
55 assert(templatepath, string.format("template `%s' not found", template))
62 env.tonumber = tonumber
63 env.tostring = tostring
68 return lp.include(templatepath, env)
71 -------------------------------------------------------------------------------
72 -- Returns a link to a html file, appending "../" to the link to make it right.
73 -- @param html Name of the html file to link to
74 -- @return link to the html file
76 function link (html, from)
79 string.gsub(from, "/", function () h = "../" .. h end)
83 -------------------------------------------------------------------------------
84 -- Returns the name of the html file to be generated from a module.
85 -- Files with "lua" or "luadoc" extensions are replaced by "html" extension.
86 -- @param modulename Name of the module to be processed, may be a .lua file or
88 -- @return name of the generated html file for the module
90 function module_link (modulename, doc, from)
91 -- TODO: replace "." by "/" to create directories?
92 -- TODO: how to deal with module names with "/"?
97 if doc.modules[modulename] == nil then
98 -- logger:error(string.format("unresolved reference to module `%s'", modulename))
102 local href = "modules/" .. modulename .. ".html"
103 string.gsub(from, "/", function () href = "../" .. href end)
107 -------------------------------------------------------------------------------
108 -- Returns the name of the html file to be generated from a lua(doc) file.
109 -- Files with "lua" or "luadoc" extensions are replaced by "html" extension.
110 -- @param to Name of the file to be processed, may be a .lua file or
112 -- @param from path of where am I, based on this we append ..'s to the
114 -- @return name of the generated html file
116 function file_link (to, from)
121 href = string.gsub(href, "lua$", "html")
122 href = string.gsub(href, "luadoc$", "html")
123 href = "files/" .. href
124 string.gsub(from, "/", function () href = "../" .. href end)
128 -------------------------------------------------------------------------------
129 -- Returns a link to a function or to a table
130 -- @param fname name of the function or table to link to.
131 -- @param doc documentation table
132 -- @param kind String specying the kinf of element to link ("functions" or "tables").
134 function link_to (fname, doc, module_doc, file_doc, from, kind)
138 kind = kind or "functions"
141 for _, func_name in pairs(file_doc[kind]) do
142 if func_name == fname then
143 return file_link(file_doc.name, from) .. "#" .. fname
148 if module_doc and module_doc[kind] then
149 for func_name, tbl in pairs(module_doc[kind]) do
150 if func_name == fname then
156 local _, _, modulename, fname = string.find(fname, "^(.-)[%.%:]?([^%.%:]*)$")
159 -- if fname does not specify a module, use the module_doc
160 if string.len(modulename) == 0 and module_doc then
161 modulename = module_doc.name
164 local module_doc = doc.modules[modulename]
165 if not module_doc then
166 -- logger:error(string.format("unresolved reference to function `%s': module `%s' not found", fname, modulename))
170 for _, func_name in pairs(module_doc[kind]) do
171 if func_name == fname then
172 return module_link(modulename, doc, from) .. "#" .. fname
176 -- logger:error(string.format("unresolved reference to function `%s' of module `%s'", fname, modulename))
179 -------------------------------------------------------------------------------
180 -- Make a link to a file, module or function
182 function symbol_link (symbol, doc, module_doc, file_doc, from)
187 -- file_link(symbol, from) or
188 module_link(symbol, doc, from) or
189 link_to(symbol, doc, module_doc, file_doc, from, "functions") or
190 link_to(symbol, doc, module_doc, file_doc, from, "tables")
193 logger:error(string.format("unresolved reference to symbol `%s'", symbol))
199 -------------------------------------------------------------------------------
200 -- Assembly the output filename for an input file.
201 -- TODO: change the name of this function
202 function out_file (filename)
204 h = string.gsub(h, "lua$", "html")
205 h = string.gsub(h, "luadoc$", "html")
207 -- h = options.output_dir .. string.gsub (h, "^.-([%w_]+%.html)$", "%1")
208 h = options.output_dir .. h
212 -------------------------------------------------------------------------------
213 -- Assembly the output filename for a module.
214 -- TODO: change the name of this function
215 function out_module (modulename)
216 local h = modulename .. ".html"
218 h = options.output_dir .. h
222 -----------------------------------------------------------------
223 -- Generate the output.
224 -- @param doc Table with the structured documentation.
227 -- Generate index file
228 if (#doc.files > 0 or #doc.modules > 0) and (not options.noindexpage) then
229 local filename = options.output_dir.."index.html"
230 logger:info(string.format("generating file `%s'", filename))
231 local f = posix.open(filename, "w")
232 assert(f, string.format("could not open `%s' for writing", filename))
234 include("index.lp", { doc = doc })
239 if not options.nomodules then
240 for _, modulename in ipairs(doc.modules) do
241 local module_doc = doc.modules[modulename]
242 -- assembly the filename
243 local filename = out_module(modulename)
244 logger:info(string.format("generating file `%s'", filename))
246 local f = posix.open(filename, "w")
247 assert(f, string.format("could not open `%s' for writing", filename))
249 include("module.lp", { doc = doc, module_doc = module_doc })
255 if not options.nofiles then
256 for _, filepath in ipairs(doc.files) do
257 local file_doc = doc.files[filepath]
258 -- assembly the filename
259 local filename = out_file(file_doc.name)
260 logger:info(string.format("generating file `%s'", filename))
262 local f = posix.open(filename, "w")
263 assert(f, string.format("could not open `%s' for writing", filename))
265 include("file.lp", { doc = doc, file_doc = file_doc} )
271 local f = posix.open(options.output_dir.."luadoc.css", "w")
273 include("luadoc.css")