diff --git a/doc/config.ld b/doc/config.ld index f45b293..b775eed 100644 --- a/doc/config.ld +++ b/doc/config.ld @@ -6,7 +6,7 @@ backtick_references=false file='../ldoc.lua' dir='../out' readme='doc.md' -style='!pale' +style='!new' kind_names={topic='Manual',script='Programs'} examples = { '../tests/styles/colon.lua', diff --git a/doc/doc.md b/doc/doc.md index 683d93c..2677313 100644 --- a/doc/doc.md +++ b/doc/doc.md @@ -433,7 +433,7 @@ examples of use; there can be multiple such tags: -- @return second part -- @usage local hello,world = split2("hello world") -- @see split - funtion split2(s,delim) .. end + function split2(s,delim) .. end Here it's assumed that 'split' is a function defined in the same module. If you wish to link to a function in another module, then the reference has to be qualified. @@ -754,8 +754,11 @@ Niklas Frykholm. For convenience, LDoc comes with a copy of markdown.lua. more features than the pure Lua version, such as PHP-Extra style tables. - [lunamark](http://jgm.github.com/lunamark/), another pure Lua processor, faster than markdown, and with extra features (`luarocks install lunamark`). + - commonmark via [cmark-lua](https://github.com/jgm/cmark-lua), a Lua wrapper +around the fast [libcmark](https://github.com/jgm/cmark) C library (`luarocks +install cmark`) -You can request the processor you like with `format = 'markdown|discount|lunamark|plain|backticks'`, and +You can request the processor you like with `format = 'markdown|discount|lunamark|commonmark|plain|backticks'`, and LDoc will attempt to use it. If it can't find it, it will look for one of the other markdown processors; the original `markdown.lua` ships with LDoc, although it's slow for larger documents. diff --git a/ldoc-scm-2.rockspec b/ldoc-scm-3.rockspec similarity index 96% rename from ldoc-scm-2.rockspec rename to ldoc-scm-3.rockspec index d294153..a3e578b 100644 --- a/ldoc-scm-2.rockspec +++ b/ldoc-scm-3.rockspec @@ -1,5 +1,5 @@ package = "ldoc" -version = "scm-2" +version = "scm-3" source = { dir="LDoc", @@ -42,6 +42,7 @@ build = { ["ldoc.html._reset_css"] = "ldoc/html/_reset_css.lua", ["ldoc.html.ldoc_one_css"] = "ldoc/html/ldoc_one_css.lua", ["ldoc.html.ldoc_pale_css"] = "ldoc/html/ldoc_pale_css.lua", + ["ldoc.html.ldoc_new_css"] = "ldoc/html/ldoc_new_css.lua", ["ldoc.html.ldoc_fixed_css"] = "ldoc/html/ldoc_fixed_css.lua", ["ldoc.builtin.globals"] = "ldoc/builtin/globals.lua", ["ldoc.builtin.coroutine"] = "ldoc/builtin/coroutine.lua", diff --git a/ldoc.lua b/ldoc.lua index 4cb9966..687df7a 100644 --- a/ldoc.lua +++ b/ldoc.lua @@ -49,7 +49,7 @@ ldoc, a documentation generator for Lua, vs ]]..version..[[ -l,--template (default !) directory for template (ldoc.ltp) -p,--project (default ldoc) project name -t,--title (default Reference) page title - -f,--format (default plain) formatting - can be markdown, discount or plain + -f,--format (default plain) formatting - can be markdown, discount, lunamark, commonmark, backticks, or plain -b,--package (default .) top-level package basename (needed for module(...)) -x,--ext (default html) output file extension -c,--config (default config.ld) configuration name @@ -573,11 +573,13 @@ if ldoc.prettify_files then 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) + if mod then + local ls = List() + for item in mod.items:iter() do + ls:append(item.lineno) + end + linemap[F.filename] = ls end - linemap[F.filename] = ls end if type(ldoc.prettify_files) == 'table' then diff --git a/ldoc/builtin/lpeg.lua b/ldoc/builtin/lpeg.lua index b2c020e..274670a 100644 --- a/ldoc/builtin/lpeg.lua +++ b/ldoc/builtin/lpeg.lua @@ -64,7 +64,7 @@ function lpeg.P(value) end -- characters with code between the codes of x and y (both inclusive). -- As an example, the pattern `lpeg.R("09")` matches any digit, and `lpeg.R("az", -- "AZ")` matches any ASCII letter. -function lpeg.R({range}) end +function lpeg.R(range) end --- -- Returns a pattern that matches any single character that appears in the given @@ -197,7 +197,7 @@ function lpeg.Ct(patt) end --- -- Creates a match-time capture. Unlike all other captures, this one is -- evaluated immediately when a match occurs. It forces the immediate evaluation --- of all its nested captures and then calls function. +-- of all its nested captures and then calls func. -- The given function gets as arguments the entire subject, the current position -- (after the match of patt), plus any capture values produced by patt. -- The first value returned by function defines how the match happens. If the @@ -209,6 +209,6 @@ function lpeg.Ct(patt) end -- match fails. -- Any extra values returned by the function become the values produced by the -- capture. -function lpeg.Cmt(patt, function) end +function lpeg.Cmt(patt, func) end return lpeg diff --git a/ldoc/html/ldoc_new_css.lua b/ldoc/html/ldoc_new_css.lua new file mode 100644 index 0000000..30191ab --- /dev/null +++ b/ldoc/html/ldoc_new_css.lua @@ -0,0 +1,292 @@ +return [[ +body { + color: #47555c; + font-size: 16px; + font-family: "Open Sans", sans-serif; + margin: 0; + background: #eff4ff; +} + +a:link { color: #008fee; } +a:visited { color: #008fee; } +a:hover { color: #22a7ff; } + +h1 { font-size:26px; font-weight: normal; } +h2 { font-size:22px; font-weight: normal; } +h3 { font-size:18px; font-weight: normal; } +h4 { font-size:16px; font-weight: bold; } + +hr { + height: 1px; + background: #c1cce4; + border: 0px; + margin: 15px 0; +} + +code, tt { + font-family: monospace; +} +span.parameter { + font-family: monospace; + font-weight: bold; + color: rgb(99, 115, 131); +} +span.parameter:after { + content:":"; +} +span.types:before { + content:"("; +} +span.types:after { + content:")"; +} +.type { + font-weight: bold; font-style:italic +} + +p.name { + font-family: "Andale Mono", monospace; +} + +#navigation { + float: left; + background-color: white; + border-right: 1px solid #d3dbec; + border-bottom: 1px solid #d3dbec; + + width: 14em; + vertical-align: top; + overflow: visible; +} + +#navigation br { + display: none; +} + +#navigation h1 { + background-color: white; + border-bottom: 1px solid #d3dbec; + padding: 15px; + margin-top: 0px; + margin-bottom: 0px; +} + +#navigation h2 { + font-size: 18px; + background-color: white; + border-bottom: 1px solid #d3dbec; + padding-left: 15px; + padding-right: 15px; + padding-top: 10px; + padding-bottom: 10px; + margin-top: 30px; + margin-bottom: 0px; +} + +#content h1 { + background-color: #2c3e67; + color: white; + padding: 15px; + margin: 0px; +} + +#content h2 { + background-color: #6c7ea7; + color: white; + padding: 15px; + padding-top: 15px; + padding-bottom: 15px; + margin-top: 0px; +} + +#content h2 a { + background-color: #6c7ea7; + color: white; + text-decoration: none; +} + +#content h2 a:hover { + text-decoration: underline; +} + +#content h3 { + font-style: italic; + padding-top: 15px; + padding-bottom: 4px; + margin-right: 15px; + margin-left: 15px; + margin-bottom: 5px; + border-bottom: solid 1px #bcd; +} + +#content h4 { + margin-right: 15px; + margin-left: 15px; + border-bottom: solid 1px #bcd; +} + +#content pre { + margin: 15px; +} + +pre { + background-color: rgb(50, 55, 68); + color: white; + border-radius: 3px; + /* border: 1px solid #C0C0C0; /* silver */ + padding: 15px; + overflow: auto; + font-family: "Andale Mono", monospace; +} + +#content ul pre.example { + margin-left: 0px; +} + +table.index { +/* border: 1px #00007f; */ +} +table.index td { text-align: left; vertical-align: top; } + +#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; +} + +#content p { + padding-left: 15px; + padding-right: 15px; +} + +#content table { + padding-left: 15px; + padding-right: 15px; + background-color: white; +} + +#content p, #content table, #content ol, #content ul, #content dl { + max-width: 900px; +} + +#about { + padding: 15px; + padding-left: 16em; + background-color: white; + border-top: 1px solid #d3dbec; + border-bottom: 1px solid #d3dbec; +} + +table.module_list, table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; + margin: 15px; +} +table.module_list td, table.function_list td { + border-width: 1px; + padding-left: 10px; + padding-right: 10px; + padding-top: 5px; + padding-bottom: 5px; + border: solid 1px rgb(193, 204, 228); +} +table.module_list td.name, table.function_list td.name { + background-color: white; min-width: 200px; border-right-width: 0px; +} +table.module_list td.summary, table.function_list td.summary { + background-color: white; width: 100%; border-left-width: 0px; +} + +dl.function { + margin-right: 15px; + margin-left: 15px; + border-bottom: solid 1px rgb(193, 204, 228); + border-left: solid 1px rgb(193, 204, 228); + border-right: solid 1px rgb(193, 204, 228); + background-color: white; +} + +dl.function dt { + color: rgb(99, 123, 188); + font-family: monospace; + border-top: solid 1px rgb(193, 204, 228); + padding: 15px; +} + +dl.function dd { + margin-left: 15px; + margin-right: 15px; + margin-top: 5px; + margin-bottom: 15px; +} + +#content dl.function dd h3 { + margin-top: 0px; + margin-left: 0px; + padding-left: 0px; + font-size: 16px; + color: rgb(128, 128, 128); + border-bottom: solid 1px #def; +} + +#content dl.function dd ul, #content dl.function dd ol { + padding: 0px; + padding-left: 15px; + list-style-type: none; +} + +ul.nowrap { + overflow:auto; + white-space:nowrap; +} + +.section-description { + padding-left: 15px; + padding-right: 15px; +} + +/* 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; } + +/* make the target distinct; helps when we're navigating to a function */ +a:target + * { + background-color: #FF9; +} + + +/* styles for prettification of source */ +pre .comment { color: #bbccaa; } +pre .constant { color: #a8660d; } +pre .escape { color: #844631; } +pre .keyword { color: #ffc090; font-weight: bold; } +pre .library { color: #0e7c6b; } +pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } +pre .string { color: #8080ff; } +pre .number { color: #f8660d; } +pre .operator { color: #2239a8; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #a33243; } +pre .global { color: #c040c0; } +pre .user-keyword { color: #800080; } +pre .prompt { color: #558817; } +pre .url { color: #272fc2; text-decoration: underline; } +]] diff --git a/ldoc/markup.lua b/ldoc/markup.lua index e34286d..d080c16 100644 --- a/ldoc/markup.lua +++ b/ldoc/markup.lua @@ -275,6 +275,15 @@ local formatters = { smart = true }) return function(text) return parse(text) end end + end, + commonmark = function(format) + local ok, cmark = pcall(require, 'cmark') + if ok then + return function(text) + local doc = cmark.parse_document(text, string.len(text), cmark.OPT_DEFAULT) + return cmark.render_html(doc, cmark.OPT_DEFAULT) + end + end end } @@ -316,7 +325,7 @@ local function markdown_processor(ldoc, formatter) return plain_processor(txt,item) end local is_file = utils.is_type(item,doc.File) - local is_module = not file and item and doc.project_level(item.type) + local is_module = not is_file and item and doc.project_level(item.type) if is_file or is_module then local deflang = 'lua' if ldoc.parse_extra and ldoc.parse_extra.C then diff --git a/readme.md b/readme.md index dae151c..0f3dbf0 100644 --- a/readme.md +++ b/readme.md @@ -6,7 +6,7 @@ Copyright (C) 2011-2012 Steve Donovan. This project grew out of the documentation needs of [Penlight](https://github.com/lunarmodules/Penlight) (and not always getting satisfaction -with LuaDoc) and depends on Penlight itself.(This allowed me to _not_ write a lot of code.) +with LuaDoc) and depends on Penlight itself. (This allowed me to _not_ write a lot of code.) The [API documentation](http://lunarmodules.github.com/Penlight/api/index.html) of Penlight is an example of a project using plain LuaDoc markup processed using LDoc. @@ -46,7 +46,7 @@ in [Lua for Windows](https://github.com/rjpcomputing/luaforwindows), and Penligh penlight`. Unpack the sources somewhere and make an alias to `ldoc.lua` on your path. That is, either -an excutable script called 'ldoc' like so: +an executable script called 'ldoc' like so: lua /path/to/ldoc/ldoc.lua $*