move extra/ to docs/gen/ and split up

7 files changed, 549 insertions, 0 deletions

diff --git a/docs/gen/dom.moon b/docs/gen/dom.moon
new file mode 100644
index 0000000..7541fbd
--- /dev/null
+++ b/docs/gen/dom.moon
@@ -0,0 +1,68 @@
+-- mmm.dom
+-- see https://mmm.s-ol.nu/meta/mmm.dom/
+
+export opairs
+
+-- ordered table iterator, for stable(r) renderers
+sort = (t, order_fn, only_strings) ->
+  with index = [k for k,v in pairs t when (not only_strings) or 'string' == type k]
+    table.sort index, order_fn
+
+-- ordered next(t)
+onext = (state, key) ->
+  state.i += state.step
+  { :t, :index, :i } = state
+
+  if key = index[i]
+    key, t[key]
+
+-- ordered pairs(t).
+-- order_fn is optional; see table.sort
+opairs = (t, order_fn, only_strings=false) ->
+  state = { :t, i: 0, step: 1, index: sort t, order_fn, only_strings }
+  onext, state, nil
+
+void_tags = { 'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr' }
+void_tags = { t,t for t in *void_tags }
+
+element = (element) -> (...) ->
+  children = { ... }
+
+  -- attributes are last arguments but mustn't be a ReactiveVar
+  attributes = children[#children]
+  if 'table' == (type attributes) and not attributes.node
+    table.remove children
+  else
+    attributes = {}
+
+  b = "<#{element}"
+  for k,v in opairs attributes, nil, true
+    if k == 'style' and 'table' == type v
+      tmp = ''
+      for kk, vv in opairs v
+        tmp ..= "#{kk}: #{vv}; "
+      v = tmp
+    b ..= " #{k}=\"#{v}\""
+
+  -- if there is only one argument,
+  -- children can be in attributes table too
+  if #children == 0
+    children = attributes
+
+  for i,v in ipairs children
+    if 'string' != type v
+      print v
+      error "wrong type: #{type v}"
+    children[i] = '' unless v
+
+  if void_tags[element]
+    assert #children == 0, "void tag #{element} cannot have children!"
+    b .. ">"
+  else
+    b ..= ">" ..  table.concat children, ''
+    b ..= "</#{element}>"
+    b
+
+setmetatable {}, __index: (name) =>
+  with val = element name
+    @[name] = val
diff --git a/docs/gen/git-version b/docs/gen/git-version
new file mode 100755
index 0000000..495b679
--- /dev/null
+++ b/docs/gen/git-version
@@ -0,0 +1,25 @@
+#!/bin/sh
+
+TAG=$(git describe --abbrev=0 HEAD)
+# REV_SHORT=$(git rev-parse --short HEAD)
+# REV_LONG=$(git rev-parse HEAD)
+
+cat <<EOF
+----
+-- \`alive\` source code version information.
+--
+-- @module version
+
+--- exports
+-- @table exports
+-- @tfield string tag the last versions git tag
+-- @tfield string web the repo web URL
+-- @tfield string repo the git repo URL
+-- @tfield string release the web URL of this release
+{
+  tag: "${TAG}"
+  web: "https://github.com/s-ol/alivecoding"
+  repo: "https://github.com/s-ol/alivecoding.git"
+  release: "https://github.com/s-ol/alivecoding/releases/tag/${TAG}"
+}
+EOF
diff --git a/docs/gen/index b/docs/gen/index
new file mode 100755
index 0000000..5b06b9d
--- /dev/null
+++ b/docs/gen/index
@@ -0,0 +1,48 @@
+#!/usr/bin/env moon
+import ValueStream from require 'alv'
+import render, layout, autoref from require 'docs.gen.layout'
+import section, h1, h2, p, ul, li, a, code from require 'docs.gen.dom'
+
+export OUT
+
+slurp = (file) ->
+  file = io.open file, 'r'
+  with file\read '*all'
+    file\close!
+
+spit = (file, str) ->
+  file = io.open file, 'w'
+  file\write str
+  file\close!
+
+{ OUT } = arg
+
+spit OUT, 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'
+      p autoref "These modules can be imported using [require][], " ..
+        "[import][] and [import*][]."
+      ul for file in *arg[2,]
+        path = file\match '^alv%-lib/(.*)%.moon$'
+        name = path\gsub '/', '.'
+        li a (code name), href: "#{path}.html"
+    }
+    section {
+      id: 'builtins'
+      h2 a "builtins", href: '#builtins'
+      p "These definitions are automatically loaded into the global Scope of
+        every alive session."
+      ul for key, val in opairs require 'alv.builtin'
+        li render key, ValueStream.wrap val
+    }
+  }
diff --git a/docs/gen/layout.moon b/docs/gen/layout.moon
new file mode 100644
index 0000000..084807e
--- /dev/null
+++ b/docs/gen/layout.moon
@@ -0,0 +1,149 @@
+version = require 'alv.version'
+dom = require 'docs.gen.dom'
+import compile from require 'discount'
+
+render_meta = (meta) ->
+  import p, code from dom
+  contents = {}
+  if meta.examples
+    -- table.insert contents, h4 'signature'
+    examples = p table.concat [code e for e in *meta.examples], ' '
+    table.insert contents, examples
+  if meta.description
+    description = compile meta.description\match '^\n*(.+)\n*$'
+    table.insert contents, description.body
+
+  contents
+
+-- render an ALV Value to a HTML string
+render = (name, value, prefix=nil, index=false) ->
+  import div, label, code, ul, li, i, a, pre from dom
+
+  id = if prefix then "#{prefix}/#{name}" else name
+  type = i value.type
+  assert value.meta, "#{id} doesn't have any metadata!"
+  summary = assert value.meta.summary, "#{id} doesn't have a summary!"
+
+  if index
+    div {
+      label (a (code name), href: "##{id}"), ' (', type, '): &ensp;&ndash;&ensp;'
+      summary
+    }
+  else
+    content = switch value.type
+      when 'scope'
+        ul for k, result in opairs value!.values
+          li render k, result.value, id
+      else
+        render_meta value.meta
+
+    content.class = 'nest'
+    div {
+      :id, class: 'def'
+      label (a (code name), href: "##{id}"), ' (', type, '): &ensp;&ndash;&ensp;'
+      summary
+      div content
+    }
+
+-- generate a relative link
+abs = (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
+-- builtin-name; mod.name/name; mod.name
+link = (ref) ->
+  return version.web if ref == '*web*'
+  return version.repo if ref == '*repo*'
+  return version.release if ref == '*release*'
+
+  mod, sym = ref\match '^(.+)/(.*)$'
+  abs "reference/#{mod or 'index'}.html##{sym or ref}"
+
+-- link to a reference
+r = (text, ref) ->
+  import a, code from dom
+  href = link ref or text
+  if ref
+    a text, :href
+  else
+    text = text\gsub '/$', ''
+    escape = ESCAPE or (i) -> i
+    a (code escape text), :href
+
+-- substitute markdown-style reference links
+autoref = (str) ->
+  str = str\gsub '%[([^%]]-)%]%[%]', r
+  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:
+--  - preamble
+--  - title
+--  - style
+--  - body (str or table)
+layout = (opts) ->
+  import header, footer, nav, div, span, b, code, a, article from dom
+
+  head = header nav {
+    span {
+      b 'alive'
+      ' '
+      a (code version.tag), href: version.release
+      ' documentation'
+    }
+    div class: 'grow'
+    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
+    "#{opts.title} - alive"
+  else
+    "alive documentation"
+  foot = footer div {
+    'alive '
+    a (code version.tag), href: version.release
+    ', generated '
+    os.date '!%Y-%m-%d %T'
+  }
+
+  "#{opts.preamble or ''}
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset=\"UTF-8\">
+    <meta name=\"viewport\" content=\"width=640\">
+
+    <title>#{title}</title>
+    <link rel=\"stylesheet\" href=\"#{opts.style or abs 'style.css'}\">
+  </head>
+  <body>
+    #{head}
+    #{body}
+    #{foot}
+  </body>
+</html>"
+
+
+{
+  :autoref
+  :render
+  :layout
+}
diff --git a/docs/gen/ldoc b/docs/gen/ldoc
new file mode 100755
index 0000000..b75740d
--- /dev/null
+++ b/docs/gen/ldoc
@@ -0,0 +1,196 @@
+#!/usr/bin/env moon
+import layout from require 'docs.gen.layout'
+
+export OUT, BASE 
+
+spit = (file, str) ->
+  file = io.open file, 'w'
+  file\write str
+  file\close!
+
+{ OUT } = arg
+BASE = '$(base)'
+
+spit OUT, layout
+  style: '$(ldoc.css)'
+  title: '$(ldoc.title)'
+  class: 'ldoc'
+  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: {
+    class: 'ldoc'
+    '
+# if ldoc.body then
+  $(ldoc.body)
+# elseif 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>
+#       if m.summary then
+    		<label><a href="$(kind)/$(m.name).html"><code>$(m.name)</code></a>:</label>
+    		<span>$(M(m.summary))</span>
+# else
+       	<label><a href="$(kind)/$(m.name).html"><code>$(m.name)</code></a></label>
+# end
+    	</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
+
+# if module.kinds()() then
+    <h2>index</h2>
+#   for kind, items in module.kinds() do
+#     kind = kind:lower()
+      <h3 class="indent">$(kind)</h3>
+      <ul>
+#     for item in items() do
+        <li>
+          <a href="#$(item.name)"><code>$(display_name(item))</code></a>
+          &ensp;&ndash;&ensp;$(M(item.summary))
+        </li>
+#     end
+      </ul>
+#   end
+
+    <h2>details</h2>
+#   for kind, items in module.kinds() do
+#     kind = kind:lower()
+      <h3 class="indent">$(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>
+          &ensp;&ndash;&ensp;$(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
+# end
+'
+  }
diff --git a/docs/gen/md b/docs/gen/md
new file mode 100755
index 0000000..32d4fdd
--- /dev/null
+++ b/docs/gen/md
@@ -0,0 +1,23 @@
+#!/usr/bin/env moon
+import layout, autoref from require 'docs.gen.layout'
+import compile from require 'discount'
+
+export OUT, ESCAPE
+
+slurp = (file) ->
+  file = io.open file, 'r'
+  with file\read '*all'
+    file\close!
+
+spit = (file, str) ->
+  file = io.open file, 'w'
+  file\write str
+  file\close!
+
+ESCAPE = (str) ->
+  (str\gsub '([*`])', '\\%1')
+
+{ OUT, file } = arg
+
+contents = slurp file
+spit OUT, layout compile (autoref contents), 'githubtags', 'fencedcode'
diff --git a/docs/gen/module b/docs/gen/module
new file mode 100755
index 0000000..143e3fe
--- /dev/null
+++ b/docs/gen/module
@@ -0,0 +1,40 @@
+#!/usr/bin/env moon
+import Scope from require 'alv'
+import render, layout from require 'docs.gen.layout'
+import section, h2, h3, ul, li, code from require 'docs.gen.dom'
+
+export OUT, require
+
+require = do
+  old_require = require
+  blacklist = {k, true for k in *{'osc', 'socket', 'system', 'luartmidi'}}
+  (mod, ...) ->
+    return {} if blacklist[mod]
+    old_require mod, ...
+
+slurp = (file) ->
+  file = io.open file, 'r'
+  with file\read '*all'
+    file\close!
+
+spit = (file, str) ->
+  file = io.open file, 'w'
+  file\write str
+  file\close!
+  
+{ OUT, module, name } = arg
+
+name or= module
+module = Scope.from_table require module
+
+spit OUT, layout
+  title: "#{name} reference"
+  body: section {
+    h2 (code name), ' module reference'
+    h3 'index'
+    ul for key, res in opairs module.values
+      li render key, res.value, nil, true
+    h3 'details'
+    ul for key, res in opairs module.values
+      li render key, res.value
+  }