2011-04-12 19:07:47 +02:00
|
|
|
---------------
|
|
|
|
-- ldoc, a Lua documentation generator.
|
|
|
|
-- Compatible with luadoc-style annoations, but providing
|
|
|
|
-- easier customization options. C/C++ support is provided.
|
|
|
|
-- Steve Donovan, 2011
|
|
|
|
|
|
|
|
require 'pl'
|
|
|
|
|
|
|
|
local append = table.insert
|
2011-07-12 14:14:55 +02:00
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
local lapp = require 'pl.lapp'
|
|
|
|
|
|
|
|
-- so we can find our private modules
|
|
|
|
app.require_here()
|
|
|
|
|
|
|
|
local args = lapp [[
|
2011-08-22 12:54:32 +02:00
|
|
|
ldoc, a documentation generator for Lua, vs 0.6
|
2011-04-13 13:04:17 +02:00
|
|
|
-d,--dir (default docs) output directory
|
2011-06-06 18:38:02 +02:00
|
|
|
-o,--output (default 'index') output name
|
2011-04-12 19:07:47 +02:00
|
|
|
-v,--verbose verbose
|
2011-06-15 16:33:13 +02:00
|
|
|
-a,--all show local functions, etc, in docs
|
2011-04-12 19:07:47 +02:00
|
|
|
-q,--quiet suppress output
|
|
|
|
-m,--module module docs as text
|
2011-06-10 11:44:12 +02:00
|
|
|
-s,--style (default !) directory for style sheet (ldoc.css)
|
|
|
|
-l,--template (default !) directory for template (ldoc.ltp)
|
2011-07-08 15:58:40 +02:00
|
|
|
-1,--one use one-column output layout
|
2011-04-12 19:07:47 +02:00
|
|
|
-p,--project (default ldoc) project name
|
|
|
|
-t,--title (default Reference) page title
|
2011-06-05 19:24:31 +02:00
|
|
|
-f,--format (default plain) formatting - can be markdown or plain
|
2011-04-17 16:31:28 +02:00
|
|
|
-b,--package (default .) top-level package basename (needed for module(...))
|
2011-06-10 11:44:12 +02:00
|
|
|
-x,--ext (default html) output file extension
|
2011-07-07 14:28:41 +02:00
|
|
|
-c,--config (default config.ld) configuration name
|
2011-04-13 18:45:41 +02:00
|
|
|
--dump debug output dump
|
2011-07-07 14:28:41 +02:00
|
|
|
--filter (default none) filter output as Lua data (e.g pl.pretty.dump)
|
2011-08-26 15:34:42 +02:00
|
|
|
--tags (default none) show all references to a given tag
|
2011-04-12 19:07:47 +02:00
|
|
|
<file> (string) source file or directory containing source
|
|
|
|
]]
|
|
|
|
|
2011-06-14 10:54:51 +02:00
|
|
|
local doc = require 'ldoc.doc'
|
2011-06-16 11:09:24 +02:00
|
|
|
local lang = require 'ldoc.lang'
|
2011-06-14 10:54:51 +02:00
|
|
|
local tools = require 'ldoc.tools'
|
2011-06-19 17:53:05 +02:00
|
|
|
local global = require 'builtin.globals'
|
2011-07-05 16:30:49 +02:00
|
|
|
local markup = require 'ldoc.markup'
|
2011-07-12 14:14:55 +02:00
|
|
|
local parse = require 'ldoc.parse'
|
2011-04-12 19:07:47 +02:00
|
|
|
local KindMap = tools.KindMap
|
2011-07-12 14:14:55 +02:00
|
|
|
local Item,File,Module = doc.Item,doc.File,doc.Module
|
|
|
|
local quit = utils.quit
|
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
|
|
|
|
class.ModuleMap(KindMap)
|
|
|
|
|
|
|
|
function ModuleMap:_init ()
|
2011-06-06 18:38:02 +02:00
|
|
|
self.klass = ModuleMap
|
|
|
|
self.fieldname = 'section'
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
ModuleMap:add_kind('function','Functions','Parameters')
|
|
|
|
ModuleMap:add_kind('table','Tables','Fields')
|
|
|
|
ModuleMap:add_kind('field','Fields')
|
2011-06-13 15:42:42 +02:00
|
|
|
ModuleMap:add_kind('lfunction','Local Functions','Parameters')
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-06-06 18:38:02 +02:00
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
class.ProjectMap(KindMap)
|
|
|
|
ProjectMap.project_level = true
|
|
|
|
|
|
|
|
function ProjectMap:_init ()
|
2011-06-06 18:38:02 +02:00
|
|
|
self.klass = ProjectMap
|
|
|
|
self.fieldname = 'type'
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
ProjectMap:add_kind('module','Modules')
|
|
|
|
ProjectMap:add_kind('script','Scripts')
|
2011-07-11 15:40:44 +02:00
|
|
|
ProjectMap:add_kind('topic','Topics')
|
2011-07-08 15:58:40 +02:00
|
|
|
ProjectMap:add_kind('example','Examples')
|
|
|
|
|
2011-07-12 14:14:55 +02:00
|
|
|
local lua, cc = lang.lua, lang.cc
|
|
|
|
|
|
|
|
local file_types = {
|
|
|
|
['.lua'] = lua,
|
|
|
|
['.ldoc'] = lua,
|
|
|
|
['.luadoc'] = lua,
|
|
|
|
['.c'] = cc,
|
|
|
|
['.cpp'] = cc,
|
|
|
|
['.cxx'] = cc,
|
|
|
|
['.C'] = cc
|
|
|
|
}
|
2011-04-12 19:07:47 +02:00
|
|
|
|
|
|
|
------- ldoc external API ------------
|
|
|
|
|
|
|
|
-- the ldoc table represents the API available in `config.ld`.
|
|
|
|
local ldoc = {}
|
2011-06-06 18:38:02 +02:00
|
|
|
local add_language_extension
|
2011-04-12 19:07:47 +02:00
|
|
|
|
|
|
|
-- aliases to existing tags can be defined. E.g. just 'p' for 'param'
|
|
|
|
function ldoc.alias (a,tag)
|
2011-06-06 18:38:02 +02:00
|
|
|
doc.add_alias(a,tag)
|
|
|
|
end
|
|
|
|
|
|
|
|
function ldoc.add_language_extension(ext,lang)
|
2011-07-12 14:14:55 +02:00
|
|
|
lang = (lang=='c' and cc) or (lang=='lua' and lua) or quit('unknown language')
|
|
|
|
if ext:sub(1,1) ~= '.' then ext = '.'..ext end
|
|
|
|
file_types[ext] = lang
|
2011-06-06 18:38:02 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
function ldoc.add_section (name,title,subname)
|
|
|
|
ModuleMap:add_kind(name,title,subname)
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
-- new tags can be added, which can be on a project level.
|
|
|
|
function ldoc.new_type (tag,header,project_level)
|
2011-06-06 18:38:02 +02:00
|
|
|
doc.add_tag(tag,doc.TAG_TYPE,project_level)
|
|
|
|
if project_level then
|
|
|
|
ProjectMap:add_kind(tag,header)
|
|
|
|
else
|
|
|
|
ModuleMap:add_kind(tag,header)
|
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-07-29 15:52:16 +02:00
|
|
|
local ldoc_contents = {
|
|
|
|
'alias','add_language_extension','new_type','add_section',
|
|
|
|
'file','project','title','package','format','output','dir','ext',
|
2011-08-22 12:54:32 +02:00
|
|
|
'one','style','template','description','examples','readme','all','extended_markdown'
|
2011-07-29 15:52:16 +02:00
|
|
|
}
|
|
|
|
ldoc_contents = tablex.makeset(ldoc_contents)
|
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
-- any file called 'config.ld' found in the source tree will be
|
|
|
|
-- handled specially. It will be loaded using 'ldoc' as the environment.
|
|
|
|
local function read_ldoc_config (fname)
|
2011-06-06 18:38:02 +02:00
|
|
|
local directory = path.dirname(fname)
|
2011-08-22 12:54:32 +02:00
|
|
|
if directory == '' then
|
|
|
|
directory = '.'
|
|
|
|
end
|
2011-06-09 12:31:05 +02:00
|
|
|
local err
|
2011-06-06 18:38:02 +02:00
|
|
|
print('reading configuration from '..fname)
|
2011-06-09 12:31:05 +02:00
|
|
|
local txt,not_found = utils.readfile(fname)
|
|
|
|
if txt then
|
|
|
|
-- Penlight defines loadin for Lua 5.1 as well
|
2011-09-11 17:47:34 +02:00
|
|
|
local chunk
|
2011-07-05 13:33:27 +02:00
|
|
|
if not loadin then -- Penlight 0.9.5
|
|
|
|
chunk,err = load(txt,nil,nil,ldoc)
|
|
|
|
else
|
|
|
|
chunk,err = loadin(ldoc,txt)
|
|
|
|
end
|
|
|
|
if chunk then
|
|
|
|
local ok
|
|
|
|
ok,err = pcall(chunk)
|
2011-09-11 17:47:34 +02:00
|
|
|
end
|
2011-06-09 12:31:05 +02:00
|
|
|
end
|
2011-09-11 17:47:34 +02:00
|
|
|
if err then quit('error loading config file '..fname..': '..err) end
|
2011-07-29 15:52:16 +02:00
|
|
|
for k in pairs(ldoc) do
|
|
|
|
if not ldoc_contents[k] then
|
|
|
|
quit("this config file field/function is unrecognized: "..k)
|
|
|
|
end
|
|
|
|
end
|
2011-06-09 12:31:05 +02:00
|
|
|
return directory, not_found
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-07-14 15:27:16 +02:00
|
|
|
local quote = tools.quote
|
2011-04-12 19:07:47 +02:00
|
|
|
--- processing command line and preparing for output ---
|
|
|
|
|
|
|
|
local F
|
|
|
|
local file_list,module_list = List(),List()
|
|
|
|
module_list.by_name = {}
|
|
|
|
local config_dir
|
|
|
|
|
|
|
|
|
2011-06-14 11:36:05 +02:00
|
|
|
local ldoc_dir = arg[0]:gsub('[^/\\]+$','')
|
|
|
|
local doc_path = ldoc_dir..'builtin/?.luadoc'
|
|
|
|
|
2011-06-19 17:53:05 +02:00
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
-- ldoc -m is expecting a Lua package; this converts this to a file path
|
|
|
|
if args.module then
|
2011-06-15 16:12:56 +02:00
|
|
|
-- first check if we've been given a global Lua lib function
|
2011-06-19 17:53:05 +02:00
|
|
|
if args.file:match '^%a+$' and global.functions[args.file] then
|
2011-06-14 11:36:05 +02:00
|
|
|
args.file = 'global.'..args.file
|
|
|
|
end
|
|
|
|
local fullpath,mod = tools.lookup_existing_module_or_function (args.file, doc_path)
|
2011-06-06 18:38:02 +02:00
|
|
|
if not fullpath then
|
2011-06-14 11:36:05 +02:00
|
|
|
quit(mod)
|
|
|
|
else
|
|
|
|
args.file = fullpath
|
|
|
|
args.module = mod
|
2011-06-06 18:38:02 +02:00
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-07-29 15:52:16 +02:00
|
|
|
local abspath = tools.abspath
|
|
|
|
|
2011-06-09 12:31:05 +02:00
|
|
|
-- a special case: 'ldoc .' can get all its parameters from config.ld
|
2011-06-10 11:44:12 +02:00
|
|
|
if args.file == '.' then
|
|
|
|
local err
|
2011-08-21 19:01:31 +02:00
|
|
|
config_dir,err = read_ldoc_config(args.config)
|
|
|
|
if err then quit("no "..quote(args.config).." found") end
|
|
|
|
local config_path = path.dirname(args.config)
|
|
|
|
if config_path ~= '' then
|
|
|
|
lfs.chdir(config_path)
|
|
|
|
end
|
2011-06-10 11:44:12 +02:00
|
|
|
config_is_read = true
|
|
|
|
args.file = ldoc.file or '.'
|
|
|
|
if args.file == '.' then
|
|
|
|
args.file = lfs.currentdir()
|
2011-07-03 10:24:14 +02:00
|
|
|
elseif type(args.file) == 'table' then
|
|
|
|
for i,f in ipairs(args.file) do
|
2011-07-29 15:52:16 +02:00
|
|
|
args.file[i] = abspath(f)
|
2011-07-03 10:24:14 +02:00
|
|
|
print(args.file[i])
|
|
|
|
end
|
2011-06-10 11:44:12 +02:00
|
|
|
else
|
2011-07-29 15:52:16 +02:00
|
|
|
args.file = abspath(args.file)
|
2011-06-10 11:44:12 +02:00
|
|
|
end
|
2011-04-17 16:31:28 +02:00
|
|
|
else
|
2011-07-29 15:52:16 +02:00
|
|
|
args.file = abspath(args.file)
|
2011-04-17 16:31:28 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
local source_dir = args.file
|
2011-07-29 15:52:16 +02:00
|
|
|
if type(source_dir) == 'table' then
|
|
|
|
source_dir = source_dir[1]
|
|
|
|
end
|
|
|
|
if type(source_dir) == 'string' and path.isfile(source_dir) then
|
2011-06-06 18:38:02 +02:00
|
|
|
source_dir = path.splitpath(source_dir)
|
2011-04-17 16:31:28 +02:00
|
|
|
end
|
|
|
|
|
2011-06-19 17:53:05 +02:00
|
|
|
---------- specifying the package for inferring module names --------
|
|
|
|
-- If you use module(...), or forget to explicitly use @module, then
|
|
|
|
-- ldoc has to infer the module name. There are three sensible values for
|
|
|
|
-- `args.package`:
|
|
|
|
--
|
|
|
|
-- * '.' the actual source is in an immediate subdir of the path given
|
|
|
|
-- * '..' the path given points to the source directory
|
|
|
|
-- * 'NAME' explicitly give the base module package name
|
|
|
|
--
|
|
|
|
|
2011-06-20 19:04:21 +02:00
|
|
|
local function setup_package_base()
|
|
|
|
if ldoc.package then args.package = ldoc.package end
|
|
|
|
if args.package == '.' then
|
2011-06-19 17:53:05 +02:00
|
|
|
args.package = source_dir
|
2011-06-20 19:04:21 +02:00
|
|
|
elseif args.package == '..' then
|
|
|
|
args.package = path.splitpath(source_dir)
|
|
|
|
elseif not args.package:find '[\//]' then
|
|
|
|
local subdir,dir = path.splitpath(source_dir)
|
|
|
|
if dir == args.package then
|
|
|
|
args.package = subdir
|
|
|
|
elseif path.isdir(path.join(source_dir,args.package)) then
|
|
|
|
args.package = source_dir
|
|
|
|
else
|
|
|
|
quit("args.package is not the name of the source directory")
|
|
|
|
end
|
2011-06-19 17:53:05 +02:00
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-06-06 18:38:02 +02:00
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
--------- processing files ---------------------
|
|
|
|
-- ldoc may be given a file, or a directory. `args.file` may also be specified in config.ld
|
|
|
|
-- where it is a list of files or directories. If specified on the command-line, we have
|
|
|
|
-- to find an optional associated config.ld, if not already loaded.
|
|
|
|
|
2011-07-03 10:24:14 +02:00
|
|
|
local function process_file (f, file_list)
|
|
|
|
local ext = path.extension(f)
|
|
|
|
local ftype = file_types[ext]
|
|
|
|
if ftype then
|
|
|
|
if args.verbose then print(path.basename(f)) end
|
2011-07-18 12:07:40 +02:00
|
|
|
local F,err = parse.file(f,ftype,args)
|
2011-07-12 14:14:55 +02:00
|
|
|
if err then quit(err) end
|
2011-07-03 10:24:14 +02:00
|
|
|
file_list:append(F)
|
|
|
|
end
|
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
local process_file_list = tools.process_file_list
|
2011-07-08 15:58:40 +02:00
|
|
|
|
2011-07-18 12:07:40 +02:00
|
|
|
setup_package_base()
|
|
|
|
|
|
|
|
|
2011-07-08 15:58:40 +02:00
|
|
|
if type(args.file) == 'table' then
|
|
|
|
-- this can only be set from config file so we can assume it's already read
|
|
|
|
process_file_list(args.file,'*.*',process_file, file_list)
|
2011-07-03 10:24:14 +02:00
|
|
|
if #file_list == 0 then quit "no source files specified" end
|
|
|
|
elseif path.isdir(args.file) then
|
2011-06-06 18:38:02 +02:00
|
|
|
local files = List(dir.getallfiles(args.file,'*.*'))
|
2011-07-08 15:58:40 +02:00
|
|
|
-- use any configuration file we find, if not already specified
|
2011-07-03 10:24:14 +02:00
|
|
|
if not config_dir then
|
|
|
|
local config_files = files:filter(function(f)
|
2011-07-07 14:28:41 +02:00
|
|
|
return path.basename(f) == args.config
|
2011-07-03 10:24:14 +02:00
|
|
|
end)
|
|
|
|
if #config_files > 0 then
|
|
|
|
config_dir = read_ldoc_config(config_files[1])
|
|
|
|
if #config_files > 1 then
|
|
|
|
print('warning: other config files found: '..config_files[2])
|
|
|
|
end
|
|
|
|
end
|
2011-06-06 18:38:02 +02:00
|
|
|
end
|
|
|
|
for f in files:iter() do
|
2011-07-03 10:24:14 +02:00
|
|
|
process_file(f, file_list)
|
2011-06-06 18:38:02 +02:00
|
|
|
end
|
2011-07-03 10:24:14 +02:00
|
|
|
if #file_list == 0 then
|
|
|
|
quit(quote(args.file).." contained no source files")
|
2011-06-21 18:39:38 +02:00
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
elseif path.isfile(args.file) then
|
2011-06-06 18:38:02 +02:00
|
|
|
-- a single file may be accompanied by a config.ld in the same dir
|
2011-06-10 11:44:12 +02:00
|
|
|
if not config_dir then
|
|
|
|
config_dir = path.dirname(args.file)
|
|
|
|
if config_dir == '' then config_dir = '.' end
|
2011-07-07 14:28:41 +02:00
|
|
|
local config = path.join(config_dir,args.config)
|
2011-07-03 10:24:14 +02:00
|
|
|
if path.isfile(config) then
|
2011-06-10 11:44:12 +02:00
|
|
|
read_ldoc_config(config)
|
|
|
|
end
|
2011-06-06 18:38:02 +02:00
|
|
|
end
|
2011-07-03 10:24:14 +02:00
|
|
|
process_file(args.file, file_list)
|
|
|
|
if #file_list == 0 then quit "unsupported file extension" end
|
2011-04-12 19:07:47 +02:00
|
|
|
else
|
2011-06-21 18:02:21 +02:00
|
|
|
quit ("file or directory does not exist: "..quote(args.file))
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
|
2011-07-10 19:12:35 +02:00
|
|
|
local multiple_files = #file_list > 1
|
|
|
|
local first_module
|
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
------ 'Special' Project-level entities ---------------------------------------
|
|
|
|
-- Examples and Topics do not contain code to be processed for doc comments.
|
|
|
|
-- Instead, they are intended to be rendered nicely as-is, whether as pretty-lua
|
|
|
|
-- or as Markdown text. Treating them as 'modules' does stretch the meaning of
|
|
|
|
-- of the term, but allows them to be treated much as modules or scripts.
|
|
|
|
-- They define an item 'body' field (containing the file's text) and a 'postprocess'
|
|
|
|
-- field which is used later to convert them into HTML. They may contain @{ref}s.
|
|
|
|
|
|
|
|
local function add_special_project_entity (f,tags,process)
|
|
|
|
local F = File(f)
|
|
|
|
tags.name = path.basename(f)
|
|
|
|
local text = utils.readfile(f)
|
|
|
|
local item = F:new_item(tags,1)
|
|
|
|
if process then
|
|
|
|
text = process(F, text)
|
|
|
|
end
|
|
|
|
F:finish()
|
|
|
|
file_list:append(F)
|
|
|
|
item.body = text
|
|
|
|
return item
|
|
|
|
end
|
|
|
|
|
2011-07-29 15:52:16 +02:00
|
|
|
if type(ldoc.examples) == 'string' then
|
|
|
|
ldoc.examples = {ldoc.examples}
|
|
|
|
end
|
2011-07-10 19:12:35 +02:00
|
|
|
if type(ldoc.examples) == 'table' then
|
|
|
|
local prettify = require 'ldoc.prettify'
|
2011-07-12 14:14:55 +02:00
|
|
|
local formatter = markup.create(ldoc,'plain')
|
|
|
|
prettify.resolve_inline_references = markup.resolve_inline_references
|
2011-07-10 19:12:35 +02:00
|
|
|
|
|
|
|
local function process_example (f, file_list)
|
2011-07-11 15:40:44 +02:00
|
|
|
local item = add_special_project_entity(f,{
|
2011-07-10 19:12:35 +02:00
|
|
|
class = 'example',
|
2011-07-11 15:40:44 +02:00
|
|
|
})
|
|
|
|
item.postprocess = prettify.lua
|
2011-07-10 19:12:35 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
process_file_list (ldoc.examples, '*.lua', process_example, file_list)
|
|
|
|
end
|
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
if type(ldoc.readme) == 'string' then
|
|
|
|
local item = add_special_project_entity(ldoc.readme,{
|
|
|
|
class = 'topic'
|
|
|
|
}, markup.add_sections)
|
|
|
|
item.postprocess = markup.create(ldoc, 'markdown')
|
|
|
|
end
|
|
|
|
|
|
|
|
---- extract modules from the file objects, resolve references and sort appropriately ---
|
2011-07-03 10:24:14 +02:00
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
local project = ProjectMap()
|
|
|
|
|
2011-07-03 10:24:14 +02:00
|
|
|
for F in file_list:iter() do
|
2011-07-08 15:58:40 +02:00
|
|
|
for mod in F.modules:iter() do
|
2011-07-10 19:12:35 +02:00
|
|
|
if not first_module then first_module = mod end
|
2011-07-08 15:58:40 +02:00
|
|
|
module_list:append(mod)
|
|
|
|
module_list.by_name[mod.name] = mod
|
|
|
|
end
|
2011-07-03 10:24:14 +02:00
|
|
|
end
|
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
for mod in module_list:iter() do
|
2011-06-06 18:38:02 +02:00
|
|
|
mod:resolve_references(module_list)
|
|
|
|
project:add(mod,module_list)
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-06-15 16:33:13 +02:00
|
|
|
-- the default is not to show local functions in the documentation.
|
2011-07-29 15:52:16 +02:00
|
|
|
if not args.all and not ldoc.all then
|
2011-06-15 16:33:13 +02:00
|
|
|
for mod in module_list:iter() do
|
|
|
|
mod:mask_locals()
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
table.sort(module_list,function(m1,m2)
|
2011-06-06 18:38:02 +02:00
|
|
|
return m1.name < m2.name
|
2011-04-12 19:07:47 +02:00
|
|
|
end)
|
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
-------- three ways to dump the object graph after processing -----
|
|
|
|
|
2011-04-12 19:07:47 +02:00
|
|
|
-- ldoc -m will give a quick & dirty dump of the module's documentation;
|
|
|
|
-- using -v will make it more verbose
|
|
|
|
if args.module then
|
2011-06-06 18:38:02 +02:00
|
|
|
if #module_list == 0 then quit("no modules found") end
|
|
|
|
if args.module == true then
|
2011-07-11 15:40:44 +02:00
|
|
|
file_list[1]:dump(args.verbose)
|
2011-06-06 18:38:02 +02:00
|
|
|
else
|
|
|
|
local fun = module_list[1].items.by_name[args.module]
|
2011-06-19 17:53:05 +02:00
|
|
|
if not fun then quit(quote(args.module).." is not part of "..quote(args.file)) end
|
2011-06-06 18:38:02 +02:00
|
|
|
fun:dump(true)
|
|
|
|
end
|
|
|
|
return
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
-- ldoc --dump will do the same as -m, except for the currently specified files
|
2011-04-13 18:45:41 +02:00
|
|
|
if args.dump then
|
2011-06-06 18:38:02 +02:00
|
|
|
for mod in module_list:iter() do
|
|
|
|
mod:dump(true)
|
|
|
|
end
|
|
|
|
os.exit()
|
2011-04-13 18:45:41 +02:00
|
|
|
end
|
2011-08-26 15:41:38 +02:00
|
|
|
if args.tags ~= 'none' then
|
2011-08-26 15:34:42 +02:00
|
|
|
local taglist = {[args.tags] = true}
|
|
|
|
for mod in module_list:iter() do
|
|
|
|
mod:dump_tags(taglist)
|
|
|
|
end
|
|
|
|
os.exit()
|
|
|
|
end
|
2011-04-13 18:45:41 +02:00
|
|
|
|
2011-07-11 15:40:44 +02:00
|
|
|
-- ldoc --filter mod.name will load the module `mod` and pass the object graph
|
|
|
|
-- to the function `name`. As a special case --filter dump will use pl.pretty.dump.
|
2011-06-19 17:53:05 +02:00
|
|
|
if args.filter ~= 'none' then
|
2011-07-11 15:40:44 +02:00
|
|
|
doc.filter_objects_through_function(args.filter, module_list)
|
2011-06-19 17:53:05 +02:00
|
|
|
os.exit()
|
|
|
|
end
|
|
|
|
|
2011-07-12 14:14:55 +02:00
|
|
|
ldoc.css, ldoc.templ = 'ldoc.css','ldoc.ltp'
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-06-10 11:44:12 +02:00
|
|
|
local function style_dir (sname)
|
|
|
|
local style = ldoc[sname]
|
|
|
|
local dir
|
|
|
|
if style then
|
|
|
|
if style == true then
|
|
|
|
dir = config_dir
|
|
|
|
elseif type(style) == 'string' and path.isdir(style) then
|
|
|
|
dir = style
|
|
|
|
else
|
2011-06-19 17:53:05 +02:00
|
|
|
quit(quote(tostring(name)).." is not a directory")
|
2011-06-10 11:44:12 +02:00
|
|
|
end
|
|
|
|
args[sname] = dir
|
|
|
|
end
|
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-06-10 11:44:12 +02:00
|
|
|
local function override (field)
|
|
|
|
if ldoc[field] then args[field] = ldoc[field] end
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
2011-06-10 11:44:12 +02:00
|
|
|
-- the directories for template and stylesheet can be specified
|
|
|
|
-- either by command-line '--template','--style' arguments or by 'template and
|
|
|
|
-- 'style' fields in config.ld.
|
|
|
|
-- The assumption here is that if these variables are simply true then the directory
|
|
|
|
-- containing config.ld contains a ldoc.css and a ldoc.ltp respectively. Otherwise
|
|
|
|
-- they must be a valid subdirectory.
|
|
|
|
|
|
|
|
style_dir 'style'
|
|
|
|
style_dir 'template'
|
|
|
|
|
|
|
|
-- can specify format, output, dir and ext in config.ld
|
|
|
|
override 'format'
|
|
|
|
override 'output'
|
|
|
|
override 'dir'
|
|
|
|
override 'ext'
|
2011-07-08 15:58:40 +02:00
|
|
|
override 'one'
|
2011-06-10 11:44:12 +02:00
|
|
|
|
2011-06-19 17:53:05 +02:00
|
|
|
if not args.ext:find '^%.' then
|
|
|
|
args.ext = '.'..args.ext
|
|
|
|
end
|
2011-06-10 11:44:12 +02:00
|
|
|
|
2011-07-08 15:58:40 +02:00
|
|
|
if args.one then
|
2011-07-12 14:14:55 +02:00
|
|
|
ldoc.css = 'ldoc_one.css'
|
2011-07-08 15:58:40 +02:00
|
|
|
end
|
|
|
|
|
2011-08-22 12:54:32 +02:00
|
|
|
if args.style == '!' or args.template == '!' then
|
|
|
|
-- '!' here means 'use built-in templates'
|
|
|
|
local tmpdir = path.join(path.is_windows and os.getenv('TMP') or '/tmp','ldoc')
|
|
|
|
if not path.isdir(tmpdir) then
|
|
|
|
lfs.mkdir(tmpdir)
|
|
|
|
end
|
|
|
|
local function tmpwrite (name)
|
|
|
|
utils.writefile(path.join(tmpdir,name),require('html.'..name:gsub('%.','_')))
|
|
|
|
end
|
|
|
|
if args.style == '!' then
|
|
|
|
tmpwrite(ldoc.templ)
|
|
|
|
args.style = tmpdir
|
|
|
|
end
|
|
|
|
if args.template == '!' then
|
|
|
|
tmpwrite(ldoc.css)
|
|
|
|
args.template = tmpdir
|
|
|
|
end
|
|
|
|
end
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-07-06 15:24:05 +02:00
|
|
|
-- create the function that renders text (descriptions and summaries)
|
|
|
|
ldoc.markup = markup.create(ldoc, args.format)
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-07-10 19:12:35 +02:00
|
|
|
|
2011-07-12 14:14:55 +02:00
|
|
|
ldoc.single = not multiple_files and first_module or nil
|
|
|
|
ldoc.log = print
|
|
|
|
ldoc.kinds = project
|
|
|
|
ldoc.modules = module_list
|
|
|
|
ldoc.title = ldoc.title or args.title
|
|
|
|
ldoc.project = ldoc.project or args.project
|
2011-07-05 18:19:49 +02:00
|
|
|
|
2011-07-12 14:14:55 +02:00
|
|
|
local html = require 'ldoc.html'
|
2011-04-12 19:07:47 +02:00
|
|
|
|
2011-07-12 14:14:55 +02:00
|
|
|
html.generate_output(ldoc, args, project)
|
2011-04-12 19:07:47 +02:00
|
|
|
|
|
|
|
if args.verbose then
|
2011-06-06 18:38:02 +02:00
|
|
|
print 'modules'
|
|
|
|
for k in pairs(module_list.by_name) do print(k) end
|
2011-04-12 19:07:47 +02:00
|
|
|
end
|
|
|
|
|
|
|
|
|