new feature: prettify_files makes per-item links to source; unless this field is 'show', don't put in index

This commit is contained in:
steve donovan 2014-10-12 16:09:09 +02:00
parent 416b541a5c
commit cfdc6f8f53
5 changed files with 65 additions and 11 deletions

View File

@ -150,6 +150,7 @@ local function setup_kinds ()
ProjectMap:add_kind(lookup('classmod','Classes'))
ProjectMap:add_kind(lookup('topic','Topics'))
ProjectMap:add_kind(lookup('example','Examples'))
ProjectMap:add_kind(lookup('file','Source'))
for k in pairs(kind_names) do
if not known_types[k] then
@ -232,7 +233,7 @@ local ldoc_contents = {
'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles',
'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references',
'dont_escape_underscore','global_lookup',
'dont_escape_underscore','global_lookup','prettify_files'
}
ldoc_contents = tablex.makeset(ldoc_contents)
@ -526,27 +527,49 @@ local function add_special_project_entity (f,tags,process)
return item, F
end
if type(ldoc.examples) == 'string' then
ldoc.examples = {ldoc.examples}
end
if type(ldoc.examples) == 'table' then
local function prettify_source_files(files,class,linemap)
local prettify = require 'ldoc.prettify'
process_file_list (ldoc.examples, '*.*', function(f)
process_file_list (files, '*.*', function(f)
local ext = path.extension(f)
local ftype = file_types[ext]
if ftype then
local item = add_special_project_entity(f,{
class = 'example',
class = class,
})
-- wrap prettify for this example so it knows which file to blame
-- if there's a problem
local lang = ext:sub(2)
item.postprocess = function(code) return prettify.lua(lang,f,code,0,true) end
item.postprocess = function(code)
return '<h2>'..path.basename(f)..'</h2>\n' ..
prettify.lua(lang,f,code,0,true,linemap and linemap[f])
end
end
end)
end
if type(ldoc.examples) == 'string' then
ldoc.examples = {ldoc.examples}
end
if type(ldoc.examples) == 'table' then
prettify_source_files(ldoc.examples,"example")
end
if ldoc.prettify_files then
local files = List()
local linemap = {}
for F in file_list:iter() do
files:append(F.filename)
local mod = F.modules[1]
local ls = List()
for item in mod.items:iter() do
ls:append(item.lineno)
end
linemap[F.filename] = ls
end
prettify_source_files(files,"file",linemap)
end
if args.simple then
ldoc.no_return_or_parms=true
ldoc.no_summary=true

View File

@ -27,7 +27,7 @@ local known_tags = {
fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N';
-- project-level
module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T',
module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T', file='T',
-- module-level
['function'] = 'T', lfunction = 'T', table = 'T', section = 'T', type = 'T',
annotation = 'T', factory = 'T';
@ -41,6 +41,7 @@ known_tags._project_level = {
topic = true,
submodule = true,
classmod = true,
file = true,
}
known_tags._code_types = {

View File

@ -152,6 +152,16 @@ function html.generate_output(ldoc, args, project)
end
return base..name..'.html'
end
-- these references are never from the index...?
function ldoc.source_ref (fun)
local modname = fun.module.name
local pack,name = tools.split_dotted_name(modname)
if not pack then
name = modname
end
return (ldoc.single and "" or "../").."source/"..name..'.lua.html#'..fun.lineno
end
function ldoc.use_li(ls)
if #ls > 1 then return '<li>','</li>' else return '','' end
@ -232,6 +242,18 @@ function html.generate_output(ldoc, args, project)
end
return names
end
-- the somewhat tangled logic that controls whether a type appears in the
-- navigation sidebar. (At least it's no longer in the template ;))
function ldoc.allowed_in_contents(type,module)
local allowed = true
if ldoc.kinds_allowed then
allowed = ldoc.kinds_allowed[type]
elseif ldoc.prettify_files and type == 'file' then
allowed = ldoc.prettify_files == 'show' or (module and module.type == 'file')
end
return allowed
end
local function set_charset (ldoc,m)
m = m or ldoc.module

View File

@ -63,7 +63,7 @@ return [==[
# -------- contents of project ----------
# local this_mod = module and module.name
# for kind, mods, type in ldoc.kinds() do
# if not ldoc.kinds_allowed or ldoc.kinds_allowed[type] then
# if ldoc.allowed_in_contents(type,module) then
<h2>$(kind)</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap'">
# for mod in mods() do local name = ldoc.module_name(mod)
@ -145,6 +145,9 @@ return [==[
<dt>
<a name = "$(item.name)"></a>
<strong>$(display_name(item))</strong>
# if ldoc.prettify_files then
<a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
# end
</dt>
<dd>
$(M(ldoc.descript(item),item))

View File

@ -26,9 +26,10 @@ local spans = {keyword=true,number=true,string=true,comment=true,global=true,bac
local cpp_lang = {c = true, cpp = true, cxx = true, h = true}
function prettify.lua (lang, fname, code, initial_lineno, pre)
function prettify.lua (lang, fname, code, initial_lineno, pre, linenos)
local res, lexer, tokenizer = List(), require 'ldoc.lexer'
local tnext = lexer.skipws
local ik = 1
if not cpp_lang[lang] then
tokenizer = lexer.lua
else
@ -50,6 +51,10 @@ function prettify.lua (lang, fname, code, initial_lineno, pre)
if not t then return nil,"empty file" end
while t do
val = escape(val)
if linenos and tok:lineno() == linenos[ik] then
res:append('<a id="'..linenos[ik]..'"></a>')
ik = ik + 1
end
if globals.functions[val] or globals.tables[val] then
t = 'global'
end