diff options
| author | Alexander Pickering <alex@cogarr.net> | 2020-07-05 17:18:56 -0400 |
|---|---|---|
| committer | Alexander Pickering <alex@cogarr.net> | 2020-07-05 17:18:56 -0400 |
| commit | e87b06ee0fe2a588b72a356bbb8378899365d626 (patch) | |
| tree | 0d0acd945a70644835e8958425e6d5e6c10196a6 | |
| parent | d2ba262c5307aa14c325ef53d8e4e56a5ece0376 (diff) | |
| download | mdoc-e87b06ee0fe2a588b72a356bbb8378899365d626.tar.gz mdoc-e87b06ee0fe2a588b72a356bbb8378899365d626.tar.bz2 mdoc-e87b06ee0fe2a588b72a356bbb8378899365d626.zip | |
Add rockspec
Add a rockspec and move the files around so that luarocks can
install it correctly
| -rw-r--r-- | README.md | 21 | ||||
| -rw-r--r-- | mdoc-dev-1.rockspec | 35 | ||||
| -rw-r--r-- | share/func.etlua.lua (renamed from func.etlua) | 4 | ||||
| -rw-r--r-- | share/funcsignature.etlua.lua (renamed from funcsignature.etlua) | 2 | ||||
| -rw-r--r-- | share/index.etlua.lua (renamed from index.etlua) | 6 | ||||
| -rw-r--r-- | share/navbar.etlua.lua (renamed from navbar.etlua) | 3 | ||||
| -rw-r--r-- | share/page.etlua.lua (renamed from page.etlua) | 24 | ||||
| -rw-r--r-- | share/style.css.lua (renamed from style.css) | 3 | ||||
| -rw-r--r-- | src/ext.lua (renamed from ext.lua) | 0 | ||||
| -rw-r--r-- | src/init.lua (renamed from init.lua) | 53 | ||||
| -rw-r--r-- | src/opt_parser.lua (renamed from opt_parser.lua) | 13 |
11 files changed, 109 insertions, 55 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..d9fb25e --- /dev/null +++ b/README.md @@ -0,0 +1,21 @@ +# MDoc
+
+## Overview
+
+A documentation engine for Lua
+
+MDoc was built after frustrations with
+[LDoc](https://stevedonovan.github.io/ldoc/manual/doc.md.html),
+the usual and most popular documentation engine for lua. Like LDoc, MDoc users
+comments in the source code to generate html files for documentation. Unlike
+LDoc, it makes no attempts to be backwards compatible with LuaDoc. This results
+in a documentation engine that is free from constraints like "One class per
+file" or "one module per file". MDoc is still in it's early stages, expect
+frequent code churn in the near future.
+
+MDoc is used to document my homebrew VR platform, [Brok\[en\]gine](https://cogarr.net/source/cgit.cgi/brokengine/),
+and you can see an example of mdoc in action in the [Brok\[en\]gine reference].
+
+## Installation
+
+The easiest way to download MDoc is with [luarocks](https://github.com/luarocks/luarocks)
diff --git a/mdoc-dev-1.rockspec b/mdoc-dev-1.rockspec new file mode 100644 index 0000000..467195e --- /dev/null +++ b/mdoc-dev-1.rockspec @@ -0,0 +1,35 @@ +package = "mdoc"
+version = "dev-1"
+source = {
+ url = "https://cogarr.net/source/cgit.cgi/mdoc",
+ tag = "v1.0"
+}
+description = {
+ summary = "A documentation tool for Lua",
+ detailed = "An alternative to LDoc, MDoc creates reference documentation from source code.",
+ homepage = "https://cogarr.net/source/cgit.cgi/mdoc/",
+ license = "BSD/2 Clause"
+}
+dependencies = {
+ "lua >= 5.1",
+ "etlua >= 1.3",
+ "luafilesystem >= 1.7"
+}
+build = {
+ type = "builtin",
+ modules = {
+ ["mdoc.opt"] = "src/opt_parser.lua",
+ ["mdoc.ext"] = "src/ext.lua",
+ ["mdoc.files.func"] = "share/func.etlua.lua",
+ ["mdoc.files.funcsignature"] = "share/funcsignature.etlua.lua",
+ ["mdoc.files.index"] = "share/index.etlua.lua",
+ ["mdoc.files.navbar"] = "share/navbar.etlua.lua",
+ ["mdoc.files.page"] = "share/page.etlua.lua",
+ ["mdoc.files.style"] = "share/style.css.lua"
+ },
+ install = {
+ bin = {
+ mdoc = "src/init.lua"
+ },
+ }
+}
diff --git a/func.etlua b/share/func.etlua.lua index f639603..f635851 100644 --- a/func.etlua +++ b/share/func.etlua.lua @@ -1,4 +1,4 @@ -
+return [[
<section>
<h4 id="<%- name %>">
<%- name %>(
@@ -40,4 +40,4 @@ <% end %>
<p> Defined at <%- data.file %>:<%- data.line %>
</section>
-
+]]
diff --git a/funcsignature.etlua b/share/funcsignature.etlua.lua index 48d92ba..de34880 100644 --- a/funcsignature.etlua +++ b/share/funcsignature.etlua.lua @@ -1,3 +1,4 @@ +return [[
<% assert(func, "Requires function to render a function signature") %>
<% assert(funcname, "Requires a function name to render a function signature") %>
<a href="#<%- funcname %>"><%- funcname %></a>(
@@ -20,3 +21,4 @@ <% end %>
<% end %>
)
+]]
diff --git a/index.etlua b/share/index.etlua.lua index 708e2b5..9f07fff 100644 --- a/index.etlua +++ b/share/index.etlua.lua @@ -1,3 +1,5 @@ +return [[
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
@@ -14,6 +16,4 @@ </article>
</body>
</html>
-
-
-
+]]
diff --git a/navbar.etlua b/share/navbar.etlua.lua index 368ea10..21192f7 100644 --- a/navbar.etlua +++ b/share/navbar.etlua.lua @@ -1,3 +1,4 @@ +return [[
<nav>
<% local sorted_headers = {} %>
<% for name,_ in pairs(headers) do %>
@@ -14,7 +15,6 @@ <% section_map[section.name] = section %>
<% end %>
<% table.sort(sorted_sections) %>
- <% print("sections:",sorted_sections) %>
<ol>
<% for _,sectionname in ipairs(sorted_sections) do %>
<% local section = section_map[sectionname] %>
@@ -23,3 +23,4 @@ </ol>
<% end %>
</nav>
+]]
diff --git a/page.etlua b/share/page.etlua.lua index 47d9ad0..6e359e6 100644 --- a/page.etlua +++ b/share/page.etlua.lua @@ -1,3 +1,4 @@ +return [[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
@@ -10,8 +11,10 @@ <body>
<%- navbar %>
<article>
- <% if header.data then %>
- <%- header.data %>
+ <% if header.data_file then %>
+ <% local reffd = io.open(header.data_file,"r") %>
+ <p><%- reffd:read("*a") %>
+ <% reffd:close() %>
<% else %>
<section>
<h3><%- header.name %></h3>
@@ -59,39 +62,30 @@ </table>
</section>
<hr>
- <% local func_fd = assert(io.open("func.etlua","r")) %>
- <% local func_sec = assert(et.compile(func_fd:read("*a"))) %>
- <% func_fd:close() %>
+ <% local func_sec = assert(et.compile(require("mdoc.files.func"))) %>
<% for _, funcname in ipairs(funcorder) do %>
<% local data = header[funcname] %>
- <% print("Data:", data) %>
<% if data.type == "method" or data.type == "function" then %>
- <% print("about to render...") %>
<%- assert(func_sec{
name = funcname,
data = data
}) %>
- <% print("done rendering...") %>
<hr>
<% elseif data.type == "field" then %>
- <% print("about to do field ") %>
<h4><%- funcname %></h4>
<p><%- data.desc or "" %>
<hr>
<% else %>
- <% print("About to do error...") %>
<% if funcname ~= "name" and funcname ~= "type" then %>
<p>Unknown field type: <%- data and data.type or "" %> for <%- funcname %>
+ <p><%- tostring(data) %>
+ <p><%- tostring(header) %>
<hr>
<% end %>
<% end %>
- <% print("Next chunk...") %>
<% end %>
- <% print("done with all chunks...") %>
<% end %>
</article>
</body>
</html>
-
-
-
+]]
diff --git a/style.css b/share/style.css.lua index ef54cec..88df99e 100644 --- a/style.css +++ b/share/style.css.lua @@ -1,3 +1,4 @@ +return [[
nav{
float:left;
padding:2em;
@@ -24,4 +25,4 @@ body{ h1,h2,h3{
line-height:1.2
}
-
+]]
@@ -6,11 +6,10 @@ Mdoc works in several steps: need updating
3. Output html documentation
]]
-local lpeg = require("lpeg")
local lfs = require("lfs")
local et = require("etlua")
-require("ext")
-local opt = require("opt_parser")
+require("mdoc.ext")
+local opt = require("mdoc.opt")
local args = {...}
local options = opt.parse_options(args)
@@ -18,7 +17,10 @@ if options.help then print(opt.help())
return
end
-print("options:",options)
+if not options.paths or #options.paths == 0 then
+ print(opt.help())
+ return
+end
local state = {
title = "",
@@ -188,10 +190,11 @@ end --Get the data for the reference documents
for dn, data in pairs(state.documents) do
- local file_name = data.path:match(".*/([^.]+)%.[^.]+$")
+ --local file_name = data.path
+ local file_name = data.path:match("([^./]+)%.[^.]+$")
local cachefile = string.format("%s/cache/documents/%s",options.output,file_name)
local out_attrs = lfs.attributes(cachefile)
- if not out_attrs or out_attrs.modification < data.lastmod then
+ if not out_attrs or out_attrs.modification < data.lastmod or options.nocache then
--we're out of date, update
local fd = assert(io.open(data.path,"r"))
local file_text = fd:read("*a")
@@ -215,7 +218,7 @@ local parse_between = { for _,file in pairs(state.files) do
local cachefilename = string.format("%s/cache/files/%s",options.output,file.relpath)
local cacheattrs = lfs.attributes(cachefilename)
- if (not cacheattrs) or cacheattrs.modification < file.lastmod then
+ if (not cacheattrs) or cacheattrs.modification < file.lastmod or options.nocache then
local chunks = {}
local in_chunk = false
local line_num = 0
@@ -422,7 +425,7 @@ for _,file in pairs(state.files) do end
local cachefilename = string.format("%s/cache/chunks/%s",options.output,file.relpath)
local cachefileattrs = lfs.attributes(cachefilename)
- if (not cachefileattrs) or cachefileattrs.modification < file.lastmod then
+ if (not cachefileattrs) or cachefileattrs.modification < file.lastmod or options.nocache then
for k,v in pairs(file.chunks) do
file.chunks[k] = process_chunk(v)
end
@@ -453,10 +456,10 @@ end --Get the data for the reference documents
if options.index ~= nil then
local file_mod = lfs.attributes(options.index).modification
- local file_name = options.index:match(".*/([^.]+)%.[^.]+$")
+ local file_name = options.index:match("([^/.]+)%.[^.]+$")
local cachefile = string.format("%s/cache/documents/%s",options.output,file_name)
local out_attrs = lfs.attributes(cachefile)
- if not out_attrs or out_attrs.modification < file_mod then
+ if not out_attrs or out_attrs.modification < file_mod or options.nocache then
--we're out of date, update
local fd = assert(io.open(options.index,"r"))
local file_text = fd:read("*a")
@@ -468,7 +471,7 @@ if options.index ~= nil then end
state.sections[file_name] = {
type = "reference",
- data_file = cachefile
+ data_file = cachefile,
}
state.index = state.sections[file_name]
end
@@ -498,16 +501,13 @@ for _,group in pairs(headers) do end
--print("headers:",headers)
-local nvfd = assert(io.open("navbar.etlua","r"))
-local navbar = assert(et.compile(nvfd:read("*a")))
-nvfd:close()
+--local nvfd = assert(io.open("../share/navbar.etlua","r"))
+local navbar = assert(et.compile(require("mdoc.files.navbar")))
local navbarhtml = navbar{headers = headers}
-local pagefd = assert(io.open("page.etlua","r"))
-local page = assert(et.compile(pagefd:read("*a")))
-pagefd:close()
-local funcsignaturefd = assert(io.open("funcsignature.etlua","r"))
-local funcsignature = assert(et.compile(funcsignaturefd:read("*a")))
-funcsignaturefd:close()
+--local pagefd = assert(io.open("../share/page.etlua","r"))
+local page = assert(et.compile(require("mdoc.files.page")))
+--local funcsignaturefd = assert(io.open("../share/funcsignature.etlua","r"))
+local funcsignature = assert(et.compile(require("mdoc.files.funcsignature")))
local sorted_headers = {}
for name,_ in pairs(headers) do
table.insert(sorted_headers,name)
@@ -535,9 +535,8 @@ for _,name in pairs(sorted_headers) do end
if options.index ~= nil then
- local indexfd = assert(io.open("index.etlua","r"))
- local index = assert(et.compile(indexfd:read("*a")))
- indexfd:close()
+ --local indexfd = assert(io.open("../share/index.etlua","r"))
+ local index = assert(et.compile(require("mdoc.files.index")))
log("state.index:",state.index)
local indextextfd = assert(io.open(state.index.data_file,"r"))
local indextext = indextextfd:read("*a")
@@ -554,12 +553,10 @@ if options.index ~= nil then end
--Copy style css
-local css = assert(io.open("style.css","r"))
+--local css = assert(io.open("style.css","r"))
+local css = assert(require("mdoc.files.style"))
local css_out = assert(io.open(options.output .. "/style.css","w"))
-for line in css:lines() do
- css_out:write(line)
-end
-css:close()
+css_out:write(css)
css_out:close()
--Generate html
diff --git a/opt_parser.lua b/src/opt_parser.lua index d99c804..5c3b28d 100644 --- a/opt_parser.lua +++ b/src/opt_parser.lua @@ -1,6 +1,6 @@ local lfs = require("lfs")
-require("ext")
+require("mdoc.ext")
local ret = {}
ret.options = {
@@ -45,6 +45,11 @@ ret.options = { consumes = 1,
default = "markdown",
},
+ nocache = {
+ type = "flag",
+ short = "-c",
+ long = "--no-cache",
+ },
--append = {
--type = "file",
--short = "-a",
@@ -126,12 +131,10 @@ for k,v in pairs(ret.options) do end
ret.parse_options = function(args)
- print("parsing args:",args)
local parsed = {}
local i = 1
while i <= #args do
local option_name = option_lookup[args[i]]
- print("found option:",option_name)
if not option_name then
errorf("Unknown option #%d: %q",i, args[i])
end
@@ -145,8 +148,6 @@ ret.parse_options = function(args) if option.consumes == 1 then
args_for_option = args_for_option[1]
end
- print("checking",option.type)
- print("with",args_for_option)
local check = assert(ret["check_" .. option.type](args_for_option))
if option.multiple then
parsed[option_name] = parsed[option_name] or {}
@@ -182,6 +183,8 @@ mdoc -p <folder> [-p <folder> ...][ -o <folder>][ -t "title"][ -i <file>][ -d <f -m | --markup-parser <executable> : Executable to use to parse the descriptions and refrence documents.
Executable should accept a file path as it's argument, and generate html as it's output.
-h | --help : print this help
+ -v | --verbose : print extra information during run
+ -c | --no-cache : rebuild files, even if they're not out of date.
]=])
end
|