Completed first part of UVLDoc
This commit is contained in:
Steven Barth
parent
ef8f835894
commit
c8ef012b3a
8 changed files with 220 additions and 14 deletions
4
Makefile
4
Makefile
|
|
@ -62,6 +62,10 @@ hostclean: clean
|
|||
apidocs: hostenv
|
||||
build/hostenv.sh $(realpath host) $(LUA_MODULEDIR) $(LUA_LIBRARYDIR) "build/makedocs.sh host/luci/ docs"
|
||||
|
||||
uvldocs: hostenv
|
||||
build/hostenv.sh $(realpath host) $(LUA_MODULEDIR) $(LUA_LIBRARYDIR) \
|
||||
"build/uvldoc $(realpath host) $(UVL_SCHEMEDIR) uvldocs $(DOCS)"
|
||||
|
||||
run:
|
||||
# make run is deprecated #
|
||||
# Please use: #
|
||||
|
|
|
|||
|
|
@ -8,6 +8,9 @@ LUA_LIBRARYDIR = /usr/lib/lua
|
|||
LUCI_MODULEDIR = $(LUA_MODULEDIR)/luci
|
||||
LUCI_LIBRARYDIR = $(LUA_LIBRARYDIR)/luci
|
||||
|
||||
UVL_SCHEMEDIR = host/lib/uci/schema
|
||||
|
||||
HTDOCS = /www
|
||||
|
||||
LUA=$(shell which lua)
|
||||
XSLTPROC=$(shell which xsltproc)
|
||||
|
|
|
|||
24
build/uvldoc
Executable file
24
build/uvldoc
Executable file
|
|
@ -0,0 +1,24 @@
|
|||
#!/usr/bin/env lua
|
||||
local fs = require "luci.fs"
|
||||
local util = require "luci.util"
|
||||
local uvldoc = require "luci.uvldoc.renderer"
|
||||
|
||||
pcall(function()
|
||||
require "uci"
|
||||
require "luci.model.uci".cursor = function(config, save)
|
||||
return uci.cursor(config or arg[1] .. "/etc/config", save or arg[1] .. "/tmp/.uci")
|
||||
end
|
||||
end)
|
||||
|
||||
local schemes = {}
|
||||
if not arg[4] or #arg[4] == 0 then
|
||||
for i, name in ipairs(fs.dir(arg[2].."/default/")) do
|
||||
if name ~= "." and name ~= ".." then
|
||||
schemes[#schemes+1] = name
|
||||
end
|
||||
end
|
||||
else
|
||||
schemes = util.split(arg[4], "[,;%s]+", nil, true)
|
||||
end
|
||||
|
||||
uvldoc.Generator(schemes, arg[3], arg[2]):make()
|
||||
|
|
@ -1,6 +1,7 @@
|
|||
<%+header.xml%>
|
||||
<h1>UCI Documentation</h1>
|
||||
<table>
|
||||
<h1 class="index-title">UCI Documentation</h1>
|
||||
<h3 class="index-subtitle">Configurations</h3>
|
||||
<table class="index">
|
||||
<% for k, v in luci.util.kspairs(self.schemes) do %>
|
||||
<tr>
|
||||
<td><a href="<%=self:_scheme_filename(k)%>"><%=k%></a></td>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<h2>LuCI UVLDoc</h2>
|
||||
<ul>
|
||||
<h2 class="menu-title">LuCI UVLDoc</h2>
|
||||
<ul class="menu-index">
|
||||
<li<%-if not scheme then%> class="menu-active"<%-end-%>>
|
||||
<a href="<%=self:_index_filename()%>">Index</a>
|
||||
</li>
|
||||
|
|
@ -8,13 +8,11 @@
|
|||
<a href="<%=self:_scheme_filename(k)%>"><%=k%></a>
|
||||
<%-if scheme == k then-%>
|
||||
<ul>
|
||||
<%-for k2, v2 in luci.util.kspairs(v.sections) do-%>
|
||||
<li>
|
||||
<a href="<%=self:_section_filename(k, k2)%>"><%=k2%></a>
|
||||
</li>
|
||||
<%-end-%>
|
||||
<%-for k2, v2 in luci.util.kspairs(v.sections) do%>
|
||||
<li><a href="<%=self:_section_filename(k, k2)%>"><%=k2%></a></li>
|
||||
<%end-%>
|
||||
</ul>
|
||||
<%-end-%>
|
||||
<%-end%>
|
||||
</li>
|
||||
<% end %>
|
||||
<%-end%>
|
||||
</ul>
|
||||
|
|
@ -1,2 +1,15 @@
|
|||
<%+header.xml%>
|
||||
<h1 class="section-title"><%=scheme-%>
|
||||
<%-if package.title then%>: <%=package.title%><%end%></h1>
|
||||
<div class="scheme-description"><%=package.description%></div>
|
||||
|
||||
<h3 class="scheme-title">Sections:</h3>
|
||||
<table class="scheme-index">
|
||||
<% for k, v in luci.util.kspairs(package.sections) do %>
|
||||
<tr>
|
||||
<td><a href="<%=self:_section_filename(scheme, k)%>"><%=k%></a></td>
|
||||
<td><%=v.title%></td>
|
||||
</tr>
|
||||
<% end %>
|
||||
</table>
|
||||
<%+footer.xml%>
|
||||
|
|
@ -1,2 +1,153 @@
|
|||
<%+header.xml%>
|
||||
<%
|
||||
local table = require "table"
|
||||
|
||||
function _parse_ref( r )
|
||||
local k, v = r:match("([^.]+)%.([^.]+)")
|
||||
return k and self:_section_filename(k, v)
|
||||
end
|
||||
|
||||
function _parse_dep( r, c, s, o )
|
||||
local ref = { }
|
||||
local vars = {
|
||||
config = c,
|
||||
section = s,
|
||||
option = o
|
||||
}
|
||||
|
||||
for v in r:gmatch("[^.]+") do
|
||||
ref[#ref+1] = (v:gsub( "%$(.+)", vars ))
|
||||
end
|
||||
|
||||
if #ref < 2 then
|
||||
table.insert(ref, 1, s or '$section')
|
||||
end
|
||||
if #ref < 3 then
|
||||
table.insert(ref, 1, c or '$config')
|
||||
end
|
||||
|
||||
return self:_variable_target(unpack(ref))
|
||||
end
|
||||
|
||||
%>
|
||||
<h1 class="section-title"><%=scheme-%>
|
||||
<%-if package.title then%>: <%=package.title%><%end%></h1>
|
||||
<h2 class="section-subtitle"><%=type-%>
|
||||
<%-if section.title then%>: <%=section.title%><%end%></h2>
|
||||
<div class="section-description"><%=section.description%></div>
|
||||
|
||||
<h3 class="section-attributes">Attributes:</h3>
|
||||
<ul class="section-attributes-index">
|
||||
<%-
|
||||
if section.required then %>
|
||||
<li class="section-attributes-required">required: <dfn>A section of this type is required.</dfn></li>
|
||||
<% end
|
||||
if section.unique then %>
|
||||
<li class="section-attributes-unique">unique: <dfn>There can be only one section of this type.</dfn></li>
|
||||
<%- else -%>
|
||||
<li class="section-attributes-multiple">multiple: <dfn>There can be more than one section of this type.</dfn></li>
|
||||
<% end
|
||||
if section.dynamic then %>
|
||||
<li class="section-attributes-dynamic">dynamic: <dfn>Sections of this type may contain user-defined options.</dfn></li>
|
||||
<% end
|
||||
if section.named then %>
|
||||
<li class="section-attributes-named">named: <dfn>Sections of this type require a name.</dfn></li>
|
||||
<% end -%>
|
||||
</ul>
|
||||
|
||||
<% if section.depends then %>
|
||||
<h3 class="section-depends">Requirements (one of):</h3>
|
||||
<ul class="section-depends-index">
|
||||
<% for i, d in ipairs(section.depends) do
|
||||
local nf = false%>
|
||||
<li>
|
||||
<% for k2, v in luci.util.kspairs(d) do
|
||||
local t = _parse_dep(k2, scheme, type)
|
||||
%>
|
||||
<% if nf then %>and<% end %>
|
||||
<%if t then%><a href="<%=t%>"><%end%><%=k2%><%if t then%></a><%end%><%if v~="" then%>=<%=v%><%end%>
|
||||
<% nf = true
|
||||
end %>
|
||||
</li>
|
||||
<% end %>
|
||||
</ul>
|
||||
<% end %>
|
||||
|
||||
<h3 class="section-variables">Options:</h3>
|
||||
<table class="section-variables-index">
|
||||
<% for k, v in luci.util.kspairs(package.variables[type]) do
|
||||
if v.required then%>
|
||||
<tr class="section-variable-required">
|
||||
<td><a href="#variable.<%=k%>"><%=k%></a></td>
|
||||
<td><%=v.title%></td>
|
||||
</tr>
|
||||
<% end end
|
||||
for k, v in luci.util.kspairs(package.variables[type]) do
|
||||
if not v.required then%>
|
||||
<tr class="section-variable-mixed">
|
||||
<td><a href="#variable.<%=k%>"><%=k%></a></td>
|
||||
<td><%=v.title%></td>
|
||||
</tr>
|
||||
<% end end %>
|
||||
</table>
|
||||
|
||||
<h3 class="section-variables">Options:</h3>
|
||||
<%-
|
||||
for i=0, 1 do
|
||||
for k, v in luci.util.kspairs(package.variables[type]) do
|
||||
if (i==0) == v.required then
|
||||
%>
|
||||
<hr />
|
||||
<div class="variable-documentation">
|
||||
<a name="variable.<%=k%>" />
|
||||
<h4 class="variable-title"><%=k-%>
|
||||
<%-if v.title then%>: <%=v.title%><%end%></h4>
|
||||
<div class="variable-description"><%=v.description%></div>
|
||||
<h5 class="variable-attributes">Attributes:</h5>
|
||||
<ul class="varaible-attributes-index">
|
||||
<% if v.required then %>
|
||||
<li class="variable-attribute-required"><strong>required</strong></li>
|
||||
<% end %>
|
||||
<li class="variable-attribute-type"><strong>Type:</strong> <%=v.type%></li>
|
||||
<li class="variable-attribute-datatype"><strong>Datatype:</strong> <%=v.datatype%></li>
|
||||
</ul>
|
||||
<% if v.depends then %>
|
||||
<h5 class="variable-depends">Dependencies (one of):</h5>
|
||||
<ul class="variable-depends-index">
|
||||
<% for i, d in ipairs(v.depends) do
|
||||
local nf = false %>
|
||||
<li>
|
||||
<% for k2, v in luci.util.kspairs(d) do
|
||||
local t = _parse_dep(k2, scheme, type, k)
|
||||
%>
|
||||
<% if nf then %>and<% end %>
|
||||
<%if t then%><a href="<%=t%>"><%end%><%=k2%><%if t then%></a><%end%><%if v~="" then%>=<%=v%><%end%>
|
||||
<% nf = true
|
||||
end %>
|
||||
</li>
|
||||
<% end %>
|
||||
</ul>
|
||||
<% end %>
|
||||
<% if v.type == "enum" then %>
|
||||
<h5 class="variable-values">Possible Values:</h5>
|
||||
<ul class="variable-values-index">
|
||||
<% for k, d in pairs(v.values) do %>
|
||||
<li><strong><%=k%></strong><%if d then%> (<%=d%>)<%end%></li>
|
||||
<% end %>
|
||||
</ul>
|
||||
<% elseif v.type == "reference" then %>
|
||||
<h5 class="variable-reference">Value references:</h5>
|
||||
<ul class="variable-reference-index">
|
||||
<% for k, d in ipairs(v.valueof) do %>
|
||||
<li>
|
||||
<% local t = _parse_ref(d)
|
||||
if t then %>Section of type <a href="<%=t%>"><% end %>
|
||||
<%=d%>
|
||||
<% if t then%></a><% end %>
|
||||
</li>
|
||||
<% end %>
|
||||
</ul>
|
||||
<% end %>
|
||||
</div>
|
||||
<% end end end -%>
|
||||
<%+footer.xml%>
|
||||
|
|
@ -20,7 +20,7 @@ local util = require "luci.util"
|
|||
local ltn12 = require "luci.ltn12"
|
||||
local template = require "luci.template"
|
||||
|
||||
local ipairs, getfenv, pairs, require = ipairs, getfenv, pairs, require
|
||||
local ipairs, getfenv, pairs, require, unpack = ipairs, getfenv, pairs, require, unpack
|
||||
local luci = luci
|
||||
|
||||
module "luci.uvldoc.renderer"
|
||||
|
|
@ -28,7 +28,7 @@ module "luci.uvldoc.renderer"
|
|||
|
||||
Generator = util.class()
|
||||
|
||||
function Generator.__init__(self, schemes, output)
|
||||
function Generator.__init__(self, schemes, output, uvlpath)
|
||||
self.names = schemes
|
||||
self.output = output or "doc"
|
||||
self.schemes = {}
|
||||
|
|
@ -55,6 +55,9 @@ function Generator.make(self)
|
|||
template.viewdir = self.sourcedir
|
||||
template.context.viewns = {
|
||||
include = function(name) template.Template(name):render(getfenv(2)) end,
|
||||
pairs = pairs,
|
||||
ipairs = ipairs,
|
||||
unpack = unpack,
|
||||
luci = luci,
|
||||
require = require
|
||||
}
|
||||
|
|
@ -108,5 +111,14 @@ function Generator._scheme_filename(self, scheme)
|
|||
end
|
||||
|
||||
function Generator._section_filename(self, scheme, section)
|
||||
return "section.%s.%s%s" % {scheme, section, self.extension}
|
||||
if self.schemes[scheme] and self.schemes[scheme].sections[section] then
|
||||
return "section.%s.%s%s" % {scheme, section, self.extension}
|
||||
end
|
||||
end
|
||||
|
||||
function Generator._variable_target(self, scheme, section, variable)
|
||||
if self.schemes[scheme] and self.schemes[scheme].variables[section] and
|
||||
self.schemes[scheme].variables[section][variable] then
|
||||
return "section.%s.%s%s#variable.%s" % {scheme, section, self.extension, variable}
|
||||
end
|
||||
end
|
||||
Loading…
Reference in a new issue