'pale' template added; interpretation of --style and --template extended
This commit is contained in:
steve donovan
parent
ad909d683b
commit
7da46268dc
|
|
@ -10,6 +10,7 @@ examples = {
|
|||
'../tests/styles/colon.lua',
|
||||
'../tests/styles/four.lua',
|
||||
'../tests/styles/three.lua',
|
||||
'../tests/styles/multiple.lua',
|
||||
'../tests/example/mylib.c',
|
||||
'../tests/moonscript/List.moon',
|
||||
}
|
||||
|
|
|
|||
58
doc/doc.md
58
doc/doc.md
|
|
@ -218,7 +218,7 @@ However, you must either use the `--colon` flag or set `colon=true` in your `con
|
|||
|
||||
In this style, types may be used directly if prefixed with '!' or '?' (for type-or-nil)
|
||||
|
||||
(see @{colon.lua})
|
||||
(see @{colon.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/colon))
|
||||
|
||||
By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified
|
||||
directory; you may point it to a single file as well. A 'project' usually consists of many
|
||||
|
|
@ -372,6 +372,11 @@ the module, but `answer` has been explicitly exported. (If you invoke LDoc with
|
|||
the `-a` flag on this file, you will see the documentation for the unexported
|
||||
function as well.)
|
||||
|
||||
`@set` is a powerful tag which assigns a configuration variable to a value _just for this module_.
|
||||
Saying `@set no_summary=true` in a module comment will temporarily disable summary generation when
|
||||
the template is expanded. Generally configuration variables that effect template expansion
|
||||
are modifiable in this way.
|
||||
|
||||
## Sections
|
||||
|
||||
LDoc supports _explicit_ sections. By default, the implicit sections correspond to the pre-existing
|
||||
|
|
@ -1028,11 +1033,37 @@ then LDoc can present this as the default value for this optional argument.
|
|||
end
|
||||
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
|
||||
|
||||
Currently the `type` and `opt` modifiers are the only ones known and used by LDoc when generating HTML
|
||||
|
||||
(See @{four.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/four))
|
||||
|
||||
An experimental feature in 1.4 allows different 'return groups' to be defined. There may be
|
||||
multiple `@return` tags, and the meaning of this is well-defined, since Lua functions may
|
||||
return multiple values. However, being a dynamic language it may return a single value if
|
||||
successful and two values (`nil`,an error message) if there is an error. This is in fact the
|
||||
convention for returning 'normal' errors (like 'file not found') as opposed to parameter errors
|
||||
(like 'file must be a string') that are often raised as errors.
|
||||
|
||||
Return groups allow a documenter to specify the various possible return values of a function,
|
||||
by specifying _number_ modifiers. All `return` tags with the same digit modifier belong together
|
||||
as a group:
|
||||
|
||||
-----
|
||||
-- function with return groups.
|
||||
-- @return[1] result
|
||||
-- @return[2] nil
|
||||
-- @return[2] error message
|
||||
function mul1() ... end
|
||||
|
||||
This is the first function in @{multiple.lua}, and the [output](http://stevedonovan.github.io/ldoc/examples/multiple)
|
||||
shows how return groups are presented, with an **Or** between the groups.
|
||||
|
||||
This is rather clumsy, and so there is a shortcut, the `@error` tag which achieves the same result,
|
||||
with helpful type information.
|
||||
|
||||
Currently the `type`,`opt` and `<digit>` modifiers are the only ones known and used by LDoc when generating HTML
|
||||
output. However, any other modifiers are allowed and are available for use with your own
|
||||
templates or for extraction by your own tools.
|
||||
|
||||
(See @{four.lua})
|
||||
|
||||
## Fields allowed in `config.ld`
|
||||
|
||||
|
|
@ -1139,7 +1170,11 @@ embedded with '$(...)'.
|
|||
|
||||
This is then styled with `ldoc.css`. Currently the template and stylesheet is very much
|
||||
based on LuaDoc, so the results are mostly equivalent; the main change that the template has
|
||||
been more generalized. The default location (indicated by '!') is the directory of `ldoc.lua`.
|
||||
been more generalized. The default location (indicated by '!') is the directory of `ldoc_ltp.lua`.
|
||||
|
||||
You will notice that the built-in templates and stylesheets end in `.lua`; this is simply to
|
||||
make it easier for LDoc to find them. Where you are customizing one or both of the template
|
||||
and stylesheet, they will have their usual extensions.
|
||||
|
||||
You may customize how you generate your documentation by specifying an alternative style
|
||||
sheet and/or template, which can be deployed with your project. The parameters are `--style`
|
||||
|
|
@ -1151,7 +1186,14 @@ be a valid directory relative to the ldoc invocation.
|
|||
An example of fully customized documentation is `tests/example/style`: this is what you
|
||||
could call 'minimal Markdown style' where there is no attempt to tag things (except
|
||||
emphasizing parameter names). The narrative alone _can_ to be sufficient, if it is written
|
||||
appropriately.
|
||||
well.
|
||||
|
||||
There are two other stylesheets available in LDoc since 1.4; the first is `ldoc_one.css` which is what
|
||||
you get from `one=true` and the second is `ldoc_pale.css`. This is a lighter theme which
|
||||
might give some relief from the heavier colours of the default. You can use this style with
|
||||
`style="!pale"` or `-s !pale`.
|
||||
See the [Lake](http://stevedonovan.github.io/lake/modules/lakelibs.html) documentation
|
||||
as an example of its use.
|
||||
|
||||
Of course, there's no reason why LDoc must always generate HTML. `--ext` defines what output
|
||||
extension to use; this can also be set in the configuration file. So it's possible to write
|
||||
|
|
@ -1159,8 +1201,10 @@ a template that converts LDoc output to LaTex, for instance. The separation of p
|
|||
and presentation makes this kind of new application possible with LDoc.
|
||||
|
||||
From 1.4, LDoc has some limited support for generating Markdown output, although only
|
||||
for single files currently. Use `--ext md` for this. 'ldoc/html/ldoc_mdtp.lua' defines
|
||||
the template for Markdown.
|
||||
for single files currently. Use `--ext md` for this. 'ldoc/html/ldoc_md_ltp.lua' defines
|
||||
the template for Markdown, but this can be overriden with `template` as above. It's another
|
||||
example of minimal structure, and provides a better place to learn about these templates than the
|
||||
rather elaborate default HTML template.
|
||||
|
||||
## Internal Data Representation
|
||||
|
||||
|
|
|
|||
56
ldoc.lua
56
ldoc.lua
|
|
@ -586,15 +586,36 @@ if args.filter ~= 'none' then
|
|||
os.exit()
|
||||
end
|
||||
|
||||
-- can specify format, output, dir and ext in config.ld
|
||||
override 'output'
|
||||
override 'dir'
|
||||
override 'ext'
|
||||
override 'one'
|
||||
override 'boilerplate'
|
||||
|
||||
-- handling styling and templates --
|
||||
ldoc.css, ldoc.templ = 'ldoc.css','ldoc.ltp'
|
||||
|
||||
-- special case: user wants to generate a .md file from a .lua file
|
||||
if args.ext == 'md' then
|
||||
ldoc.templ = 'ldoc.mdtp'
|
||||
if #module_list ~= 1 then
|
||||
quit("can currently only generate Markdown output from one module only")
|
||||
end
|
||||
if ldoc.template == '!' then
|
||||
ldoc.template = '!md'
|
||||
end
|
||||
args.output = module_list[1].name
|
||||
args.dir = '.'
|
||||
ldoc.template_escape = '>'
|
||||
ldoc.style = false
|
||||
args.ext = '.md'
|
||||
end
|
||||
|
||||
local function match_bang (s)
|
||||
if type(s) ~= 'string' then return end
|
||||
return s:match '^!(.*)'
|
||||
end
|
||||
|
||||
local function style_dir (sname)
|
||||
local style = ldoc[sname]
|
||||
local dir
|
||||
|
|
@ -605,7 +626,7 @@ local function style_dir (sname)
|
|||
if style then
|
||||
if style == true then
|
||||
dir = config_dir
|
||||
elseif type(style) == 'string' and path.isdir(style) then
|
||||
elseif type(style) == 'string' and (path.isdir(style) or match_bang(style)) then
|
||||
dir = style
|
||||
else
|
||||
quit(quote(tostring(style)).." is not a directory")
|
||||
|
|
@ -614,7 +635,6 @@ local function style_dir (sname)
|
|||
end
|
||||
end
|
||||
|
||||
|
||||
-- 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.
|
||||
|
|
@ -625,35 +645,41 @@ end
|
|||
style_dir 'style'
|
||||
style_dir 'template'
|
||||
|
||||
-- can specify format, output, dir and ext in config.ld
|
||||
override 'output'
|
||||
override 'dir'
|
||||
override 'ext'
|
||||
override 'one'
|
||||
override 'boilerplate'
|
||||
|
||||
if not args.ext:find '^%.' then
|
||||
args.ext = '.'..args.ext
|
||||
end
|
||||
|
||||
if args.one then
|
||||
ldoc.css = 'ldoc_one.css'
|
||||
ldoc.style = '!one'
|
||||
end
|
||||
|
||||
if args.style == '!' or args.template == '!' then
|
||||
local builtin_style, builtin_template = match_bang(args.style),match_bang(args.template)
|
||||
if builtin_style or builtin_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('ldoc.html.'..name:gsub('%.','_')))
|
||||
local ok,text = pcall(require,'ldoc.html.'..name:gsub('%.','_'))
|
||||
if not ok then
|
||||
quit("cannot find builtin template "..name..": "..text)
|
||||
end
|
||||
if not utils.writefile(path.join(tmpdir,name),text) then
|
||||
quit("cannot write to temp directory "..tmpdir)
|
||||
end
|
||||
end
|
||||
if builtin_style then
|
||||
if builtin_style ~= '' then
|
||||
ldoc.css = 'ldoc_'..builtin_style..'.css'
|
||||
end
|
||||
if args.style == '!' then
|
||||
tmpwrite(ldoc.css)
|
||||
args.style = tmpdir
|
||||
end
|
||||
if args.template == '!' then
|
||||
if builtin_template then
|
||||
if builtin_template ~= '' then
|
||||
ldoc.templ = 'ldoc_'..builtin_template..'.ltp'
|
||||
end
|
||||
tmpwrite(ldoc.templ)
|
||||
args.template = tmpdir
|
||||
end
|
||||
|
|
|
|||
|
|
@ -0,0 +1,297 @@
|
|||
return [[/* BEGIN RESET
|
||||
|
||||
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
|
||||
Code licensed under the BSD License:
|
||||
http://developer.yahoo.com/yui/license.html
|
||||
version: 2.8.2r1
|
||||
*/
|
||||
html {
|
||||
color: #000;
|
||||
background: #FFF;
|
||||
}
|
||||
body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
border-spacing: 0;
|
||||
}
|
||||
fieldset,img {
|
||||
border: 0;
|
||||
}
|
||||
address,caption,cite,code,dfn,em,strong,th,var,optgroup {
|
||||
font-style: inherit;
|
||||
font-weight: inherit;
|
||||
}
|
||||
del,ins {
|
||||
text-decoration: none;
|
||||
}
|
||||
li {
|
||||
list-style: bullet;
|
||||
margin-left: 20px;
|
||||
}
|
||||
caption,th {
|
||||
text-align: left;
|
||||
}
|
||||
h1,h2,h3,h4,h5,h6 {
|
||||
font-size: 100%;
|
||||
font-weight: bold;
|
||||
}
|
||||
q:before,q:after {
|
||||
content: '';
|
||||
}
|
||||
abbr,acronym {
|
||||
border: 0;
|
||||
font-variant: normal;
|
||||
}
|
||||
sup {
|
||||
vertical-align: baseline;
|
||||
}
|
||||
sub {
|
||||
vertical-align: baseline;
|
||||
}
|
||||
legend {
|
||||
color: #000;
|
||||
}
|
||||
input,button,textarea,select,optgroup,option {
|
||||
font-family: inherit;
|
||||
font-size: inherit;
|
||||
font-style: inherit;
|
||||
font-weight: inherit;
|
||||
}
|
||||
input,button,textarea,select {*font-size:100%;
|
||||
}
|
||||
/* END RESET */
|
||||
|
||||
body {
|
||||
margin-left: 1em;
|
||||
margin-right: 1em;
|
||||
font-family: arial, helvetica, geneva, sans-serif;
|
||||
background-color: #ffffff; margin: 0px;
|
||||
}
|
||||
|
||||
code, tt { font-family: monospace; }
|
||||
span.parameter { font-family:monospace; }
|
||||
span.parameter:after { content:":"; }
|
||||
span.types:before { content:"("; }
|
||||
span.types:after { content:")"; }
|
||||
.type { font-weight: bold; font-style:italic }
|
||||
|
||||
body, p, td, th { font-size: .95em; line-height: 1.2em;}
|
||||
|
||||
p, ul { margin: 10px 0 0 0px;}
|
||||
|
||||
strong { font-weight: bold;}
|
||||
|
||||
em { font-style: italic;}
|
||||
|
||||
h1 {
|
||||
font-size: 1.5em;
|
||||
margin: 0 0 20px 0;
|
||||
}
|
||||
h2, h3, h4 { margin: 15px 0 10px 0; }
|
||||
h2 { font-size: 1.25em; }
|
||||
h3 { font-size: 1.15em; }
|
||||
h4 { font-size: 1.06em; }
|
||||
|
||||
a:link { font-weight: bold; color: #004080; text-decoration: none; }
|
||||
a:visited { font-weight: bold; color: #006699; text-decoration: none; }
|
||||
a:link:hover { text-decoration: underline; }
|
||||
|
||||
hr {
|
||||
color:#cccccc;
|
||||
background: #00007f;
|
||||
height: 1px;
|
||||
}
|
||||
|
||||
blockquote { margin-left: 3em; }
|
||||
|
||||
ul { list-style-type: disc; }
|
||||
|
||||
p.name {
|
||||
font-family: "Andale Mono", monospace;
|
||||
padding-top: 1em;
|
||||
}
|
||||
|
||||
pre.example {
|
||||
background-color: rgb(245, 245, 245);
|
||||
border: 1px solid silver;
|
||||
padding: 10px;
|
||||
margin: 10px 0 10px 0;
|
||||
font-family: "Andale Mono", monospace;
|
||||
font-size: .85em;
|
||||
}
|
||||
|
||||
pre {
|
||||
background-color: rgb(245,245,255); // rgb(245, 245, 245);
|
||||
border: 1px solid #cccccc; //silver;
|
||||
padding: 10px;
|
||||
margin: 10px 0 10px 0;
|
||||
overflow: auto;
|
||||
font-family: "Andale Mono", monospace;
|
||||
}
|
||||
|
||||
|
||||
table.index { border: 1px #00007f; }
|
||||
table.index td { text-align: left; vertical-align: top; }
|
||||
|
||||
#container {
|
||||
margin-left: 1em;
|
||||
margin-right: 1em;
|
||||
background-color: #f0f0f0;
|
||||
}
|
||||
|
||||
#product {
|
||||
text-align: center;
|
||||
border-bottom: 1px solid #cccccc;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
|
||||
#product big {
|
||||
font-size: 2em;
|
||||
}
|
||||
|
||||
#main {
|
||||
background-color:#FFFFFF; // #f0f0f0;
|
||||
//border-left: 2px solid #cccccc;
|
||||
}
|
||||
|
||||
#navigation {
|
||||
float: left;
|
||||
width: 14em;
|
||||
vertical-align: top;
|
||||
background-color:#FFFFFF; // #f0f0f0;
|
||||
overflow: visible;
|
||||
}
|
||||
|
||||
#navigation h2 {
|
||||
background-color:#FFFFFF;//:#e7e7e7;
|
||||
font-size:1.1em;
|
||||
color:#000000;
|
||||
text-align: left;
|
||||
padding:0.2em;
|
||||
//border-top:1px solid #dddddd;
|
||||
border-bottom:1px solid #dddddd;
|
||||
}
|
||||
|
||||
#navigation ul
|
||||
{
|
||||
font-size:1em;
|
||||
list-style-type: none;
|
||||
margin: 1px 1px 10px 1px;
|
||||
}
|
||||
|
||||
#navigation li {
|
||||
text-indent: -1em;
|
||||
display: block;
|
||||
margin: 3px 0px 0px 22px;
|
||||
}
|
||||
|
||||
#navigation li li a {
|
||||
margin: 0px 3px 0px -1em;
|
||||
}
|
||||
|
||||
#content {
|
||||
margin-left: 14em;
|
||||
padding: 1em;
|
||||
width: 700px;
|
||||
border-left: 2px solid #cccccc;
|
||||
// border-right: 2px solid #cccccc;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
|
||||
#about {
|
||||
clear: both;
|
||||
padding: 5px;
|
||||
border-top: 2px solid #cccccc;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
|
||||
@media print {
|
||||
body {
|
||||
font: 12pt "Times New Roman", "TimeNR", Times, serif;
|
||||
}
|
||||
a { font-weight: bold; color: #004080; text-decoration: underline; }
|
||||
|
||||
#main {
|
||||
background-color: #ffffff;
|
||||
border-left: 0px;
|
||||
}
|
||||
|
||||
#container {
|
||||
margin-left: 2%;
|
||||
margin-right: 2%;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
|
||||
#content {
|
||||
padding: 1em;
|
||||
background-color: #ffffff;
|
||||
}
|
||||
|
||||
#navigation {
|
||||
display: none;
|
||||
}
|
||||
pre.example {
|
||||
font-family: "Andale Mono", monospace;
|
||||
font-size: 10pt;
|
||||
page-break-inside: avoid;
|
||||
}
|
||||
}
|
||||
|
||||
table.module_list {
|
||||
border-width: 1px;
|
||||
border-style: solid;
|
||||
border-color: #cccccc;
|
||||
border-collapse: collapse;
|
||||
}
|
||||
table.module_list td {
|
||||
border-width: 1px;
|
||||
padding: 3px;
|
||||
border-style: solid;
|
||||
border-color: #cccccc;
|
||||
}
|
||||
table.module_list td.name { background-color: #f0f0f0; ; min-width: 200px; }
|
||||
table.module_list td.summary { width: 100%; }
|
||||
|
||||
table.function_list {
|
||||
border-width: 1px;
|
||||
border-style: solid;
|
||||
border-color: #cccccc;
|
||||
border-collapse: collapse;
|
||||
}
|
||||
table.function_list td {
|
||||
border-width: 1px;
|
||||
padding: 3px;
|
||||
border-style: solid;
|
||||
border-color: #cccccc;
|
||||
}
|
||||
table.function_list td.name { background-color: #f6f6ff; ; min-width: 200px; }
|
||||
table.function_list td.summary { width: 100%; }
|
||||
|
||||
dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
|
||||
dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
|
||||
dl.table h3, dl.function h3 {font-size: .95em;}
|
||||
|
||||
/* stop sublists from having initial vertical space */
|
||||
ul ul { margin-top: 0px; }
|
||||
ol ul { margin-top: 0px; }
|
||||
ol ol { margin-top: 0px; }
|
||||
ul ol { margin-top: 0px; }
|
||||
|
||||
/* styles for prettification of source */
|
||||
pre .comment { color: #558817; }
|
||||
pre .constant { color: #a8660d; }
|
||||
pre .escape { color: #844631; }
|
||||
pre .keyword { color: #2239a8; font-weight: bold; }
|
||||
pre .library { color: #0e7c6b; }
|
||||
pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
|
||||
pre .string { color: #a8660d; }
|
||||
pre .number { color: #f8660d; }
|
||||
pre .operator { color: #2239a8; font-weight: bold; }
|
||||
pre .preprocessor, pre .prepro { color: #a33243; }
|
||||
pre .global { color: #800080; }
|
||||
pre .prompt { color: #558817; }
|
||||
pre .url { color: #272fc2; text-decoration: underline; }
|
||||
]]
|
||||
Loading…
Reference in New Issue