doc: add website live example

Author: yuchanns

.github/workflows/pages.yml

@@ -0,0 +1,70 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build Web Site
+    if: github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/master'
+    runs-on: ubuntu-22.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Build Soluna (WASM)
+        uses: ./.github/actions/soluna
+        id: build
+        with:
+          soluna_path: "."
+
+      - name: Install web build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y lua5.4 zip
+
+      - name: Prepare web assets
+        run: |
+          lua5.4 script/build_web.lua \
+            --soluna . \
+            --site web \
+            --wasm "${{ steps.build.outputs.SOLUNA_WASM_PATH }}" \
+            --js "${{ steps.build.outputs.SOLUNA_JS_PATH }}"
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: "0.119.0"
+
+      - name: Build
+        run: hugo --source web --minify
+
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: web/public
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/master'
+    needs: [build]
+    runs-on: ubuntu-22.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -5,3 +5,7 @@ bin/macos
 bin/mingw
 bin/msvc
 bin/emcc
+web/public
+web/data
+web/static/runtime
+web/static/data

script/build_web.lua

@@ -0,0 +1,242 @@
+local function trim(s)
+  return (s:gsub("^%s+", ""):gsub("%s+$", ""))
+end
+
+local function shell_quote(value)
+  return "'" .. value:gsub("'", "'\\''") .. "'"
+end
+
+local function run(cmd)
+  local ok = os.execute(cmd)
+  if ok ~= true and ok ~= 0 then
+    error("command failed: " .. cmd)
+  end
+end
+
+local function read_file(path)
+  local f = assert(io.open(path, "rb"))
+  local data = f:read("*a")
+  f:close()
+  return data
+end
+
+local function write_file(path, data)
+  local f = assert(io.open(path, "wb"))
+  f:write(data)
+  f:close()
+end
+
+local function read_lines(path)
+  local f = assert(io.open(path, "r"))
+  local lines = {}
+  for line in f:lines() do
+    lines[#lines + 1] = line
+  end
+  f:close()
+  return lines
+end
+
+local function exec_lines(cmd)
+  local p = assert(io.popen(cmd, "r"))
+  local lines = {}
+  for line in p:lines() do
+    if line ~= "" then
+      lines[#lines + 1] = line
+    end
+  end
+  p:close()
+  return lines
+end
+
+local function is_array(tbl)
+  local count = 0
+  for k, _ in pairs(tbl) do
+    if type(k) ~= "number" then
+      return false
+    end
+    count = count + 1
+  end
+  for i = 1, count do
+    if tbl[i] == nil then
+      return false
+    end
+  end
+  return true
+end
+
+local function json_escape(value)
+  return value
+    :gsub("\\", "\\\\")
+    :gsub("\"", "\\\"")
+    :gsub("\b", "\\b")
+    :gsub("\f", "\\f")
+    :gsub("\n", "\\n")
+    :gsub("\r", "\\r")
+    :gsub("\t", "\\t")
+end
+
+local function json_encode(value)
+  local t = type(value)
+  if t == "nil" then
+    return "null"
+  elseif t == "boolean" then
+    return value and "true" or "false"
+  elseif t == "number" then
+    return tostring(value)
+  elseif t == "string" then
+    return "\"" .. json_escape(value) .. "\""
+  elseif t == "table" then
+    if is_array(value) then
+      local parts = {}
+      for i = 1, #value do
+        parts[#parts + 1] = json_encode(value[i])
+      end
+      return "[" .. table.concat(parts, ",") .. "]"
+    end
+    local parts = {}
+    for k, v in pairs(value) do
+      parts[#parts + 1] = json_encode(k) .. ":" .. json_encode(v)
+    end
+    table.sort(parts)
+    return "{" .. table.concat(parts, ",") .. "}"
+  else
+    error("unsupported json type: " .. t)
+  end
+end
+
+local function titleize(name)
+  local parts = {}
+  for part in name:gmatch("[^_%-%s]+") do
+    parts[#parts + 1] = part:sub(1, 1):upper() .. part:sub(2)
+  end
+  return table.concat(parts, " ")
+end
+
+local function parse_doc_file(path)
+  local blocks = {}
+  local doc_lines = {}
+  local annos = {}
+
+  local function flush(signature)
+    if #doc_lines == 0 and #annos == 0 then
+      return
+    end
+    blocks[#blocks + 1] = {
+      signature = signature,
+      docs = doc_lines,
+      annos = annos,
+    }
+    doc_lines = {}
+    annos = {}
+  end
+
+  for _, line in ipairs(read_lines(path)) do
+    if line:match("^%-%-%-@") then
+      annos[#annos + 1] = trim(line:gsub("^%-%-%-@", ""))
+    elseif line:match("^%-%-%-") then
+      doc_lines[#doc_lines + 1] = trim(line:gsub("^%-%-%-%s?", ""))
+    else
+      local trimmed = trim(line)
+      if trimmed ~= "" and (#doc_lines > 0 or #annos > 0) then
+        flush(trimmed)
+      end
+    end
+  end
+  flush(nil)
+  return blocks
+end
+
+local function parse_args(argv)
+  local opts = {
+    soluna = ".",
+    site = "web",
+    wasm = nil,
+    js = nil,
+  }
+  local i = 1
+  while i <= #argv do
+    local arg = argv[i]
+    if arg == "--soluna" then
+      opts.soluna = argv[i + 1]
+      i = i + 2
+    elseif arg == "--site" then
+      opts.site = argv[i + 1]
+      i = i + 2
+    elseif arg == "--wasm" then
+      opts.wasm = argv[i + 1]
+      i = i + 2
+    elseif arg == "--js" then
+      opts.js = argv[i + 1]
+      i = i + 2
+    else
+      error("unknown argument: " .. arg)
+    end
+  end
+  if not opts.wasm or not opts.js then
+    error("missing --wasm or --js argument")
+  end
+  return opts
+end
+
+local opts = parse_args(arg)
+local soluna_dir = opts.soluna
+local site_dir = opts.site
+local runtime_dir = site_dir .. "/static/runtime"
+local data_dir = site_dir .. "/data"
+local static_data_dir = site_dir .. "/static/data"
+
+run("mkdir -p " .. shell_quote(runtime_dir))
+run("mkdir -p " .. shell_quote(runtime_dir .. "/test"))
+run("mkdir -p " .. shell_quote(data_dir))
+run("mkdir -p " .. shell_quote(static_data_dir))
+
+run("cp " .. shell_quote(opts.wasm) .. " " .. shell_quote(runtime_dir .. "/soluna.wasm"))
+run("cp " .. shell_quote(opts.js) .. " " .. shell_quote(runtime_dir .. "/soluna.js"))
+
+run("cd " .. shell_quote(soluna_dir) .. " && zip -r " .. shell_quote(runtime_dir .. "/asset.zip") .. " asset")
+run("cp -R " .. shell_quote(soluna_dir .. "/test/.") .. " " .. shell_quote(runtime_dir .. "/test"))
+
+local examples = {}
+local example_paths = exec_lines("find " .. shell_quote(soluna_dir .. "/test") .. " -maxdepth 1 -type f -name '*.lua' -print")
+table.sort(example_paths)
+for _, path in ipairs(example_paths) do
+  local name = path:match("([^/]+)%.lua$")
+  if name then
+    local content = read_file(path)
+    if not content:find("font%.system") then
+      examples[#examples + 1] = {
+        id = name,
+        title = titleize(name),
+        entry = "test/" .. name .. ".lua",
+      }
+    end
+  end
+end
+
+local docs = {}
+local doc_paths = exec_lines("find " .. shell_quote(soluna_dir .. "/docs") .. " -maxdepth 1 -type f -name '*.lua' -print")
+table.sort(doc_paths)
+for _, path in ipairs(doc_paths) do
+  local name = path:match("([^/]+)%.lua$")
+  if name then
+    docs[#docs + 1] = {
+      module = name,
+      title = titleize(name),
+      blocks = parse_doc_file(path),
+    }
+  end
+end
+
+local examples_payload = json_encode({
+  generated_at = os.date("!%Y-%m-%dT%H:%M:%SZ"),
+  examples = examples,
+})
+write_file(data_dir .. "/examples.json", examples_payload)
+write_file(static_data_dir .. "/examples.json", examples_payload)
+
+local docs_payload = json_encode({
+  generated_at = os.date("!%Y-%m-%dT%H:%M:%SZ"),
+  modules = docs,
+})
+write_file(data_dir .. "/docs.json", docs_payload)
+write_file(static_data_dir .. "/docs.json", docs_payload)

test/imageloader.lua

@@ -1,3 +1,3 @@
-local setting = require "soluna.setting"
+local soluna = require "soluna"
 
-print_r(setting)
+print_r(soluna.settings())

test/setting.lua

@@ -3,16 +3,10 @@ local spritemgr = require "soluna.spritemgr"
 -- texture size = 128
 local bank = spritemgr.newbank(65536, 128)
 
-local ids = {
-	bank:add(32, 16),
-	bank:add(64, 32),
-	bank:add(96, 96),
-	bank:add(96, 96),
-}
-
-for _, id in ipairs(ids) do
-	bank:touch(id)
-end
+bank:add(32, 16)
+bank:add(64, 32)
+bank:add(96, 96)
+bank:add(96, 96)
 
 local texid, n = bank:pack()
 print("Pack",n,"from",texid)

test/spritepack.lua

@@ -0,0 +1,9 @@
+baseURL = "/"
+title = "Soluna Web Lab"
+languageCode = "en-us"
+paginate = 12
+relativeURLs = true
+canonifyURLs = true
+
+[params]
+  description = "Soluna documentation and live examples running in the browser."

web/config.toml

@@ -0,0 +1,4 @@
+---
+title: "Soluna Web Lab"
+description: "Live docs and examples for the Soluna engine."
+---

web/content/_index.md

@@ -0,0 +1,4 @@
+---
+title: "Docs"
+description: "Soluna API reference."
+---

web/content/docs/_index.md

@@ -0,0 +1,4 @@
+---
+title: "Examples"
+description: "Gallery of Soluna test entries."
+---