Use doctool

This commit is contained in:
Matthias Richter 2012-10-19 15:37:41 +02:00
parent 510a5b1551
commit fbcacd413d
7 changed files with 3612 additions and 2103 deletions

3
.gitmodules vendored Normal file
View File

@ -0,0 +1,3 @@
[submodule "doctool"]
path = doctool
url = git@github.com:vrld/doctool.git

1748
doc.lua

File diff suppressed because it is too large Load Diff

1
doctool Submodule

@ -0,0 +1 @@
Subproject commit 72f4c13759edf79a6780096a3278bfedbb4ed3e7

241
doctool-theme.lua Normal file
View File

@ -0,0 +1,241 @@
local discount = function(s) return (require 'discount')(s, "nopants") end
local actions = {}
local function filter(t, p)
local r = {}
for _,v in ipairs(t) do
if p(v) then r[#r+1] = v end
end
return r
end
-- generic
function actions.textblock(info)
return discount(info[1])
end
function actions.section(info)
local htype = 'h'..(info[3]+1)
if info[3] >= 3 then
return table.concat{
'<div class="section-block" id="{{MODULE}}', info[1], '">',
'<',htype,'>', info[1], '<a class="top" href="#{{MODULE}}">^top</a></',htype,'>',
discount(info[4]),
'</div>'
}
end
return table.concat{
'<div class="outer-block" id="{{MODULE}}', info[1], '">',
'<',htype,'>', info[1], '<a class="top" href="#top">^top</a></',htype,'>',
'<div class="preamble">', discount(info[4]), '</div>',
'</div>'
}
end
-- function
function actions.parameters(info)
return discount(info[1]):gsub('<dt>([^<]+)</dt>', function(m)
local type, what, optional = m:match("(%S+) ([^%(]+)( %b())")
if not type then
optional, type, what = '', m:match("(%S+) ([^%(]+)%s*")
end
assert(type and what and optional, "Invalid parameter description: " .. m)
return table.concat{'<dt>', type, ' <code>', what, '</code>', optional, '</dt>'}
end)
end
function actions.returns(info)
return discount(info[1])
end
function actions.example(info)
return discount(info[1])
end
function actions.sketch(info)
return discount(info[1])
end
actions['function'] = function(info)
local arg_delim = info.has_table_args and {'{','}'} or {'(',')'}
local out = {
'<div class="ref-block" id="{{MODULE}}', info[1], '">',
'<h4>',
'function <span class="name">', info[1], '</span>',
'<span class="arglist">', arg_delim[1], info[2], arg_delim[2], '</span>',
'<a class="top" href="#{{MODULE}}">^top</a></h4>',
discount(info[4])
}
-- parameter list
local parameters = filter(info[5], function(v) return v.type == 'parameters' end)
out[#out+1] = '<div class="arguments">'
out[#out+1] = 'Parameters:'
if #parameters == 0 then
out[#out+1] = '<dl><dt>None</dt></dl>'
else
for _, r in ipairs(parameters) do
out[#out+1] = actions.parameters(r)
end
end
out[#out+1] = '</div>'
-- returns list
local returns = filter(info[5], function(v) return v.type == 'returns' end)
out[#out+1] = '<div class="returns">'
out[#out+1] = 'Returns:'
if #returns == 0 then
out[#out+1] = '<dl><dt>Nothing</dt></dl>'
else
for _, r in ipairs(returns) do
out[#out+1] = actions.returns(r)
end
end
out[#out+1] = '</div>'
-- examples
local examples = filter(info[5], function(v) return v.type == 'example' end)
assert(#examples > 0, "No examples given for function " .. info[1] .. "()")
out[#out+1] = '<div class="example">'
out[#out+1] = #examples > 1 and 'Examples:' or 'Example:'
for _,s in ipairs(examples) do
out[#out+1] = actions.example(s)
end
out[#out+1] = '</div>'
-- sketch
local sketch = filter(info[5], function(v) return v.type == 'sketch' end)
if #sketch > 0 then
out[#out+1] = '<div class="example">'
out[#out+1] = #sketch > 1 and 'Sketches:' or 'Sketch:'
for _,s in ipairs(sketch) do
out[#out+1] = actions.sketch(s)
end
out[#out+1] = '</div>'
end
out[#out+1] = '</div>'
return table.concat(out)
end
-- module
function actions.module(info)
local modname = info[1]
local out = {
'<div class="outer-block" id="', modname, '">',
'<h3>', modname, '<a class="top" href="#top">^top</a></h3>',
'<div class="preamble">', discount(info[3]), '</div>'
}
-- create module overview
out[#out+1] = '<div class="overview">'
out[#out+1] = '<h4>Module overview</h4>'
out[#out+1] = '<dl>'
for _,info in ipairs(info[4]) do
if info.type == 'function' then
out[#out+1] = table.concat{
'<dt>',
'<a href="#', modname, info[1], '">',
info[1], '()',
'</a>',
'</dt><dd>',
info[3],
'</dd>',
}
elseif info.type == 'section' then
out[#out+1] = table.concat{
'<dt>',
'<a href="#', modname, info[1], '">',
info[1],
'</a>',
'</dt><dd>',
info[2],
'</dd>',
}
else
error("Unhandled module subtype: " .. info.type)
end
end
out[#out+1] = '</dl>'
out[#out+1] = '</div>'
-- create detailed reference
for _,info in ipairs(info[4]) do
local s = actions[info.type](info)
out[#out+1] = s:gsub('{{MODULE}}', modname)
end
out[#out+1] = '</div>'
return table.concat(out)
end
-- title
function actions.title(info)
--return table.concat{'<h1>', info[1], '</h1>'}
return ""
end
-- build module overview
function actions.preprocess(doctree)
local out = {}
out[#out+1] = '<dl>'
for _, info in ipairs(filter(doctree, function(v) return v.type == 'module' end)) do
out[#out+1] = table.concat{
'<dt><a href="#', info[1], '">', info[1], '</a></dt>',
'<dd>', info[2], '</dd>',
}
end
out[#out+1] = '</dl>'
local mod_overview = {type = 'section', 'Modules', '', 2, table.concat(out)}
for i = 1,#doctree do
if doctree[i][1] == 'Introduction' then
table.insert(doctree, i+1, mod_overview)
break
end
end
return doctree
end
function actions.postprocess(out)
return table.concat{[[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>hump - L&Ouml;VE Helper Utilities for More Productivity</title>
<link rel="stylesheet" type="text/css" href="style.css" />
<link rel="stylesheet" type="text/css" href="highlight.css" />
<script type="text/javascript" src="highlight.pack.js"></script>
<script type="text/javascript">
window.onload = function() {
var examples = document.getElementsByTagName("code");
for (i = 0; i < examples.length; ++i) {
if (examples[i].className == "lua")
hljs.highlightBlock(examples[i], " ");
}
};
</script>
</head>
<body><a name="top"></a>
<div id="header">
<h1><a href="http://github.com/vrld/hump">hump</a>
<span class="small"> Helper Utilities for More Productivity</span></h1>
<ul id="main-nav">
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Modules">Modules</a></li>
<li><a href="#License">License</a></li>
<li><a href="#Download">Download</a></li>
</ul>
<h2>&nbsp;</h2>
</div>]],
out:gsub('{{MODULE}}', ''):gsub('<code>', '<code class="lua">'),
"</body></html>"
}
end
return actions

2241
documentation.md Normal file

File diff suppressed because it is too large Load Diff

1225
index.html

File diff suppressed because one or more lines are too long

View File

@ -1,256 +0,0 @@
function markup(str)
local function trim(tbl)
for i=#tbl,1,-1 do
if tbl[i] == ' ' then
tbl[i] = nil
else
return tbl
end
end
end
local parse, block, block2, element, code, url, title, def, dt, dd
function parse(out, next)
local c = next()
if not c then return out end
if c == ' ' or c == '\t' then return parse(out, next) end
out[#out+1] = '<p>'
if c == '[' then return element(out, next) end
out[#out+1] = c
return block(out, next)
end
function block(out, next)
local c = next()
if not c then out[#out+1] = '</p>' return out end
if c == '[' then return element(out, next) end
if c == '\n' then return block2(out, next) end
out[#out+1] = c
return block(out, next)
end
function block2(out, next)
local c = next()
if not c then out[#out+1] = '</p>' return out end
if c == '[' then return element(out, next) end
if c == '\n' then out[#out+1] = '</p>' return parse(out, next) end
if c ~= ' ' and c ~= '\t' then out[#out+1] = c
elseif out[#out] ~= ' ' then out[#out+1] = ' ' end
return block(out, next)
end
function element(out, next)
local c = assert(next(), 'markup error')
if c == '^' then out[#out+1] = '<a href="' return url(out, next) end
if c == '|' then out[#out+1] = '<dl>' return def(out, next) end
if c == '%' then out[#out+1] = '<pre><code class="lua">' return code(out, next) end
out[#out+1] = '['..c
return block(out, next)
end
function url(out, next)
local c = assert(next(), 'markup error')
assert(c ~= ']', 'incomplete link definition')
if c == ' ' then out[#out+1] = '">' return title(out, next) end
out[#out+1] = c
return url(out, next)
end
function title(out, next)
local c = assert(next(), 'markup error')
if c == ']' then out[#out+1] = '</a>' return block(out, next) end
out[#out+1] = c
return title(out, next)
end
function def(out, next)
local c = assert(next(), 'markup error')
if c == ' ' or c == '\t' or c == '\n' then return def(out, next) end
if c == ']' then out[#out+1] = '</dl>' return block(out, next) end
out[#out+1] = '<dt>' .. c
return dt(out, next)
end
function dt(out, next)
local c = assert(next(), 'markup error')
if c == ':' then trim(out) out[#out+1] = '</dt><dd>' return dd(out, next) end
out[#out+1] = c
return dt(out, next)
end
function dd(out, next)
local c = assert(next(), 'markup error')
if c == '\n' then out[#out+1] = '</dd>' return def(out, next) end
out[#out+1] = c
return dd(out, next)
end
function code(out, next)
local c = assert(next(), 'markup error')
if c == ']' then out[#out+1] = '</code></pre>' return block(out, next) end
out[#out+1] = c
return code(out, next)
end
local function spans(m)
local cmd,rest = m:match('^{(.)(.+)}$')
if cmd == '#' then return '<code class="lua">'..rest..'</code>' end
if cmd == '*' then return '<em>'..rest..'</em>' end
if cmd == '!' then return '<span class="warning">'..rest..'</span>' end
return m
end
return table.concat(parse({}, str:gmatch('.'))):gsub('%b{}', spans):gsub('%b{}', spans)
end
-- PREPARE DOCUMENTATION MARKUP
local DOC = { short = {}, long = {} }
function Module(M)
for _,field in ipairs{'name', 'title', 'short', 'long'} do
assert(M[field], "Module: Required field `"..field.."' is missing")
end
DOC.short[#DOC.short+1] = ('<dt><a href="#%s">%s</a></dt><dd>%s</dd>'):format(M.title, M.name, M.short)
local long = {}
local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
F('<a name="%s" id="%s"></a>', M.title, M.title)
F('<div class="outer-block">') -- outer block>
F('<h3>%s<a class="top" href="#top">^ top</a></h3>', M.name)
F('<div class="preamble">') -- preamble>
F('<pre><code class="lua">%s = require "%s"</code></pre>', M.title:gsub("^(%w+)%W.+", "%1"), M.name)
F(markup(M.long))
F('</div>') -- <preamble
F('<div class="overview"><h4>Module overview</h4><dl>') -- overview>
for _,item in ipairs(M) do if item.short then F(item.short) end end
F('</dl></div>') -- <overview
for _,item in ipairs(M) do F(item.long) end
F('</div>') -- <outer block
DOC.long[#DOC.long+1] = table.concat(long):gsub('{{MODULE}}', M.title)
end
function Section(M)
for _,field in ipairs{'name', 'title', 'content'} do
assert(M[field], "Section: Required field `"..field.."' is missing")
end
local short = ('<dt><a href="#{{MODULE}}-%s">%s</a></dt><dd>%s</dd>'):format(M.name, M.name, M.title)
local long = {}
local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
F('<a name="{{MODULE}}-%s" id="{{MODULE}}-%s"></a>', M.name, M.name)
F('<div class="section-block"><h4>%s<a class="top" href="#{{MODULE}}">^ top</a></h4>', M.title) -- section block>
F(markup(M.content))
if M.example then
if type(M.example) ~= 'table' then M.example = {M.example} end
F('<div class="example">Example:')
for i=1,#M.example do
F('<pre><code class="lua">')
F(M.example[i])
F('</code></pre>')
end
F('</div>')
end
F('</div>') -- <section block
return {short = short, long = table.concat(long)}
end
function Function(M)
for _,field in ipairs{'name', 'short', 'long', 'params', 'returns', 'example'} do
assert(M[field], "Function: Required field `"..field.."' is missing")
end
if type(M.name) ~= 'table' then M.name = {M.name} end
if type(M.short) ~= 'table' then M.short = {M.short} end
assert(#M.name >= #M.short)
local short = {}
for i=1,#M.short do
short[i] = ('<dt><a href="#{{MODULE}}-%s">%s()</a></dt><dd>%s</dd>'):format(M.name[i], M.name[i], M.short[i])
end
short = table.concat(short)
local args
if #M.params == 0 then
args = '()'
elseif M.params.table_argument then
args = {}
for i,p in ipairs(M.params) do
if p.name then
args[i] = p.name..' = '.. p[2]
else
args[i] = p[2]
end
end
args = '{'..table.concat(args, ', ')..'}'
else
args = {}
for i,p in ipairs(M.params) do
args[i] = p[2]
end
args = '('..table.concat(args, ', ')..')'
end
local long = {}
local function F(s, ...) long[#long+1] = select('#', ...) > 0 and s:format(...) or s end
-- header(s)
for i=1,#M.name do F('<a name="{{MODULE}}-%s" id="{{MODULE}}-%s"></a>', M.name[i], M.name[i]) end
F('<div class="ref-block">')
for i=1,#M.name do
F('<h4>function <span class="name">%s</span><span class="arglist">%s</span><a class="top" href="#{{MODULE}}">^ top</a></h4>', M.name[i], args) -- section block>
end
-- description
F(markup(M.long))
-- parameters
F('<div class="arguments">Parameters:<dl>')
if #M.params == 0 then F('<dt>None</dt>') end
for _,p in ipairs(M.params) do
F('<dt>%s <code>%s</code>%s</dt><dd>%s</dd>', p[1], p[2], p.optional and ' (optional)' or '', markup(p[3]):sub(4,-5))
end
F('</dl></div>')
-- return values
F('<div class="returns">Returns:<dl>')
if #M.returns == 0 then F('<dt>Nothing</dt>') end
for _,r in ipairs(M.returns) do
F('<dt>%s</dt><dd>%s</dd>', r[1], markup(r[2]):sub(4,-5))
end
F('</dl></div>')
-- example(s)
if type(M.example) ~= 'table' then M.example = {M.example} end
F('<div class="example">Example:')
for i=1,#M.example do
F('<pre><code class="lua">')
F(M.example[i])
F('</code></pre>')
end
F('</div>')
-- sketch
if M.sketch then
F('<div class="example">Sketch:<img src="%s" width="%s" height="%s" /></div>', M.sketch[1], M.sketch.width, M.sketch.height)
end
F('</div>') -- <section block
return {short = short, long = table.concat(long)}
end
dofile(...) -- magic
-- ASSEMBLE DOCUMENTATION MARKUP
io.write([[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><title>hump - L&Ouml;VE Helper Utilities for More Productivity</title><link rel="stylesheet" type="text/css" href="style.css" /><link rel="stylesheet" type="text/css" href="highlight.css" /><script type="text/javascript" src="highlight.pack.js"></script><script type="text/javascript">window.onload = function() {var examples = document.getElementsByTagName("code");for (i = 0; i < examples.length; ++i) {if (examples[i].className == "lua")hljs.highlightBlock(examples[i], " ");}};</script></head><body><a name="top" id="top"></a><div id="header"><h1><a href="http://github.com/vrld/hump">hump</a><span class="small"> Helper Utilities for More Productivity</span></h1><ul id="main-nav"><li><a href="#intro">Introduction</a></li><li><a href="#doc">Documentation</a></li><li><a href="#license">License</a></li><li><a href="#download">Download</a></li></ul><h2>&nbsp;</h2></div><a name="intro" id="intro"></a><div class="outer-block"><h3>Introduction<a class="top" href="#top">^ top</a></h3><div class="preamble"><p><em>Helper Utilities for a Multitude of Problems</em> is a set of lightweight helpers for the <strong>awesome</strong> <a href="http://love2d.org/">L&Ouml;VE</a> Engine.</p><p><em>hump</em> differs from other libraries in that every component is independent of the remaining ones. <em>hump</em>'s footprint is very small and thus should fit nicely into your projects.</p></div></div><a name="doc"></a><div class="outer-block"><h3>Documentation<a class="top" href="#top">^ top</a></h3><div class="preamble">]])
io.write('<dl>'..table.concat(DOC.short):gsub('Ö', '&Ouml;')..'</dl>')
io.write([[</div></div>]])
io.write(''..table.concat(DOC.long):gsub('Ö', '&Ouml;'))
io.write[[<a name="license" id="license"></a><div class="outer-block"><h3>License<a class="top" href="#top">^ top</a></h3><div class="preamble"><p>Yay, <em>free software</em>:</p><blockquote><p>Copyright (c) 2010 Matthias Richter</p><p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p><p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p><p>Except as contained in this notice, the name(s) of the above copyright holders shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.</p><p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p></blockquote></div></div><a name="download" id="download"></a><div class="outer-block"><h3>Download<a class="top" href="#top">^ top</a></h3><div class="preamble"><p>You can view and download the individual modules on github: <a href="http://github.com/vrld/hump">vrld/hump</a>. You may also download the whole packed sourcecode either in <a href="http://github.com/vrld/hump/zipball/master">zip</a> or <a href="http://github.com/vrld/hump/tarball/master">tar</a> formats.</p><p>You can clone the project with <a href="http://git-scm.com">Git</a> by running: <pre>git clone git://github.com/vrld/hump</pre> Once done, you can check for updates by running <pre>git pull</pre></p></div></div></body>]]