'pale' template added; interpretation of --style and --template extended

This commit is contained in:
steve donovan 2013-08-25 19:38:01 +02:00
parent ad909d683b
commit 7da46268dc
5 changed files with 390 additions and 22 deletions

View File

@ -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',
}

View File

@ -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

View File

@ -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 args.style == '!' then
if builtin_style then
if builtin_style ~= '' then
ldoc.css = 'ldoc_'..builtin_style..'.css'
end
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

297
ldoc/html/ldoc_pale_css.lua Normal file
View File

@ -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; }
]]