From 7da46268dc528431228440f52a17146dc3a29dde Mon Sep 17 00:00:00 2001 From: steve donovan Date: Sun, 25 Aug 2013 19:38:01 +0200 Subject: [PATCH] 'pale' template added; interpretation of --style and --template extended --- doc/config.ld | 1 + doc/doc.md | 58 +++- ldoc.lua | 56 +++- ldoc/html/{ldoc_mdtp.lua => ldoc_md_ltp.lua} | 0 ldoc/html/ldoc_pale_css.lua | 297 +++++++++++++++++++ 5 files changed, 390 insertions(+), 22 deletions(-) rename ldoc/html/{ldoc_mdtp.lua => ldoc_md_ltp.lua} (100%) create mode 100644 ldoc/html/ldoc_pale_css.lua diff --git a/doc/config.ld b/doc/config.ld index 1d01883..b37025d 100644 --- a/doc/config.ld +++ b/doc/config.ld @@ -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', } diff --git a/doc/doc.md b/doc/doc.md index b6177b3..77bbe8b 100644 --- a/doc/doc.md +++ b/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 `` 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 diff --git a/ldoc.lua b/ldoc.lua index 9c58974..e00d42e 100644 --- a/ldoc.lua +++ b/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 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 diff --git a/ldoc/html/ldoc_mdtp.lua b/ldoc/html/ldoc_md_ltp.lua similarity index 100% rename from ldoc/html/ldoc_mdtp.lua rename to ldoc/html/ldoc_md_ltp.lua diff --git a/ldoc/html/ldoc_pale_css.lua b/ldoc/html/ldoc_pale_css.lua new file mode 100644 index 0000000..fe72012 --- /dev/null +++ b/ldoc/html/ldoc_pale_css.lua @@ -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; } +]]