diff options
Diffstat (limited to 'extra')
| -rw-r--r-- | extra/docs.moon | 182 | ||||
| -rwxr-xr-x | extra/git-version.sh | 2 | ||||
| -rw-r--r-- | extra/layout.moon | 35 |
3 files changed, 204 insertions, 15 deletions
diff --git a/extra/docs.moon b/extra/docs.moon index 3afa340..ae59d6a 100644 --- a/extra/docs.moon +++ b/extra/docs.moon @@ -1,8 +1,8 @@ import Value, Scope from require 'core' import render, layout, autoref from require 'extra.layout' -import section, h2, p, ul, li, a, code, r from require 'extra.dom' +import section, h1, h2, p, ul, li, a, code, r from require 'extra.dom' -export OUT, require +export OUT, BASE, require { OUT, command } = arg slurp = (file) -> @@ -41,6 +41,13 @@ spit OUT, switch command layout title: 'reference' body: { + h1 (code 'alive'), " language reference" + p "This section documents all builtins and modules that are currently + available in the alive programming language." + p autoref "If you are new to alive, the [getting started guide][:../guide/:] is + the recommended place to start. If you are looking for + information on adding your own module or contributing to alive, check + out the [developer documentation][:../internals/index/:]." section { id: 'modules' h2 a "module index", href: '#modules' @@ -70,5 +77,176 @@ spit OUT, switch command layout compile autoref contents, 'githubtags', 'fencedcode' + when 'ldoc' + BASE = '$(base)' + layout + style: '$(ldoc.css)' + title: '$(ldoc.title)' + preamble: ' +# local iter = ldoc.modules.iter +# local M = ldoc.markup +# local function display_name(item) +# if item.type == "function" then +# return item.name:gsub(":new$", "")..item.args +# else return item.name end +# end +# local function use_li(ls) +# if #ls > 1 then return "<li>","</li>" else return "","" end +# end +# local base = module and "../../" or "../"' + body: ' +# if not module then +# if ldoc.description then + <h1>$(M(ldoc.description))</h1> +# end +# if ldoc.full_description then + <p>$(M(ldoc.full_description))</p> +#end + +# for kind, mods in ldoc.kinds() do +# kind = kind:lower() + <h2>$(kind)</h2> + <ul> +# for m in mods() do + <li> + <label><a href="$(kind)/$(m.name).html"><code>$(m.name)</code></a>:</label> + <span>$(M(m.summary))</span> + </tr> +# end + </ul> +# end +# else + <h1>$(ldoc.module_typename(module):lower()) <code>$(module.name)</code></h1> + <p>$(M(module.summary, module))</p> + <p>$(M(module.description, module))</p> + +# if module.see then +# local li,il = use_li(module.see) + <h3>see also:</h3> + <ul> +# for see in iter(module.see) do + $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il) +# end + </ul> +# end + + <h2>index</h2> +# for kind, items in module.kinds() do + <h3>$(kind)</h3> + <ul> +# for item in items() do + <li> + <a href="#$(item.name)"><code>$(display_name(item))</code></a> +  – $(M(item.summary)) + </li> +# end + </ul> +# end + + <h2>details</h2> +# for kind, items in module.kinds() do + <h3>$(kind)</h3> + <ul> +# for item in items() do + <li class="def" id="$(item.name)"> + <label> + <a href="#$(item.name)"><code>$(display_name(item))</code></a> + </label> +  – $(M(item.summary)) + <div class="nest"> + $(M(item.description)) + +# if item.usage then +# local li,il = use_li(item.usage) + <h4>usage:</h4> + <ul> +# for usage in iter(item.usage) do + $(li)<pre class="example"><code>$(usage)</code></pre>$(il) +# end + </ul> +# end + +# if item.params and #item.params > 0 then +# local subnames = module.kinds:type_of(item).subnames +# if subnames then + <h4>$(subnames:lower()):</h4> +# end + <ul> +# for parm in iter(item.params) do +# local param,sublist = item:subparam(parm) +# for p in iter(param) do +# local name = item:display_name_of(p) +# local tp = ldoc.typename(item:type_of_param(p)) +# local def = item:default_of_param(p) +# local desc = item.params.map[p] +# local col = desc and desc ~= "" and ":" or "" + <li> + <label> + <code>$(name)</code> +# if tp ~= "" then + ($(tp))$(col) +# else + $(col) +# end + </label> + $(M(desc,item)) +# if def == true then + (<em>optional</em>) +# elseif def then + (<em>default</em> $(def)) +# end + </li> +# end +# end + </ul> +# end + +# if item.retgroups then local groups = item.retgroups + <h4>returns:</h4> +# for i,group in ldoc.ipairs(groups) do + <ol> +# for r in group:iter() do +# local type, ctypes = item:return_type(r) +# local rt = ldoc.typename(type) +# local col = r.text and r.text ~= "" and ":" or "" + <li> +# if rt ~= "" then + ($(rt))$(col) +# end + $(M(r.text,item)) +# if ctypes then + <ul> +# for c in ctypes:iter() do + <li><span class="parameter">$(c.name)</span> + <span class="types">$(ldoc.typename(c.type))</span> + $(M(c.comment,item))</li> +# end + </ul> +# end + </li> +# end + </ol> +# if i < #groups then + <h4>or</h4> +# end +# end +# end + +# if item.usage then +# local li,il = use_li(item.usage) + <h4>usage:</h4> + <ul> +# for usage in iter(item.usage) do + $(li)<pre class="example">$(ldoc.prettify(usage))</pre>$(il) +# end + </ul> +# end + </div> + </li> +# end +</ul> +# end +# end +' else error "unknown command '#{command}'" diff --git a/extra/git-version.sh b/extra/git-version.sh index 612bea4..1c90d8c 100755 --- a/extra/git-version.sh +++ b/extra/git-version.sh @@ -6,7 +6,7 @@ REV_LONG=`git rev-parse HEAD` cat <<EOF ---- --- \`alive\` source code version information +-- \`alive\` source code version information. -- -- @module version diff --git a/extra/layout.moon b/extra/layout.moon index 3f2024a..dfc8116 100644 --- a/extra/layout.moon +++ b/extra/layout.moon @@ -2,7 +2,7 @@ v = require 'core.version' -- render an ALV Value to a HTML string render = (name, value, prefix=nil) -> - import div, label, code, ul, li, i, a, p from require 'extra.dom' + import div, label, code, ul, li, i, a, pre from require 'extra.dom' id = if prefix then "#{prefix}/#{name}" else name type = i value.type @@ -12,7 +12,7 @@ render = (name, value, prefix=nil) -> ul for k, result in opairs value!.values li render k, result.value, id when 'opdef', 'builtin' - p value!.doc + pre value!.doc when 'num', 'str', 'bool' code tostring value! @@ -24,11 +24,14 @@ render = (name, value, prefix=nil) -> -- generate a relative link abs = (page) -> - assert OUT, "OUT needs to be set" - relative = assert (OUT\match '^docs/(.*)'), "unexpected output path" - _, depth = relative\gsub '/', '/' - up = string.rep '../', depth - "#{up}#{page}" + if BASE + "#{BASE}#{page}" + else + assert OUT, "OUT needs to be set" + relative = assert (OUT\match '^docs/(.*)'), "unexpected output path" + _, depth = relative\gsub '/', '/' + up = string.rep '../', depth + "#{up}#{page}" -- generate a link to a reference entry -- entry is one of @@ -53,6 +56,12 @@ autoref = (str) -> str = str\gsub '%[([^%]]-)%]%[:(.-):%]', r str +aopts = (href, pat) -> + { + href: abs href + class: if OUT\match "^docs/#{pat}" then 'active' + } + -- layout and write a doc page -- opts: -- - title @@ -68,9 +77,10 @@ layout = (opts) -> ' documentation' } div class: 'grow' - a 'home', href: abs 'index.html' - a 'getting started', href: abs 'guide.html' - a 'reference', href: abs 'reference/index.html' + a 'home', aopts 'index.html', 'index.html$' + a 'getting started', aopts 'guide.html', 'guide.html$' + a 'reference', aopts 'reference/index.html', 'reference' + a 'internals', aopts 'internals/index.html', 'ldoc' } body = article opts.body title = if opts.title @@ -84,14 +94,15 @@ layout = (opts) -> os.date '!%Y-%m-%d %T' } - "<!DOCTYPE html> + "#{opts.preamble or ''} +<!DOCTYPE html> <html> <head> <meta charset=\"UTF-8\"> <meta name=\"viewport\" content=\"width=640\"> <title>#{title}</title> - <link rel=\"stylesheet\" href=\"#{abs 'style.css'}\"> + <link rel=\"stylesheet\" href=\"#{opts.style or abs 'style.css'}\"> #{opts.css or ''} </head> <body> |