gen1recomp/tools/gen_registry_docs.lua

-- Renders Reference-Registries.md from Schemas.REGISTRIES so the reference
-- page cannot drift from the engine.  Run from the repo root:
--   luajit tools/gen_registry_docs.lua [outputDir]
--
-- The book lives in the GitHub wiki, so the target is a wiki checkout:
--   luajit tools/gen_registry_docs.lua ../gen1recomp.wiki
--   POKEPORT_DOCS_DIR=../project.wiki luajit tools/gen_registry_docs.lua
-- The full doc pipeline moves into the modkit CLI later; this is the
-- Schemas -> markdown seed it will absorb.
package.path = "./?.lua;./?/init.lua;" .. package.path

local Schemas = require("src.mods.Schemas")

-- the book lives in the GitHub wiki, so the default target is a sibling
-- wiki checkout; pass a directory or set POKEPORT_DOCS_DIR to override
local DEFAULT_DIR = "../gen1recomp.wiki"
local FILE = "Reference-Registries.md"

-- precedence: argv, env, default -- so a wiki checkout is one flag away and
-- a CI job can set it once for every generator that grows this convention
local outDir = (... or nil)
if outDir == nil or outDir == "" then outDir = os.getenv("POKEPORT_DOCS_DIR") end
if outDir == nil or outDir == "" then outDir = DEFAULT_DIR end
outDir = outDir:gsub("/+$", "")

local OUT = outDir .. "/" .. FILE

local names = {}
for name in pairs(Schemas.REGISTRIES) do names[#names + 1] = name end
table.sort(names)

local out = {}
local function line(fmt, ...)
  if select("#", ...) > 0 then
    out[#out + 1] = fmt:format(...)
  else
    out[#out + 1] = fmt
  end
end

line("<!-- Generated by tools/gen_registry_docs.lua from src/mods/Schemas.lua.")
line("     Do not edit by hand; regenerate after any schema change. -->")
line("")
line("# Registry reference")
line("")
line("One section per registry: merge semantics, the `Data` table the merge")
line("writes, and the value schema. Concepts and verbs:")
line("[Concepts: Registries](Concepts-Registries).")

for _, name in ipairs(names) do
  local spec = Schemas.REGISTRIES[name]
  line("")
  line("## %s", name)
  line("")
  line("- semantics: `%s`", spec.semantics)
  line("- target: %s", spec.target and ("`Data." .. spec.target .. "`") or "none")
  if spec.deprecated then
    line("- **deprecated** -- use %s", spec.deprecated.useInstead)
  end
  if spec.keys then
    line("")
    line("Id = a top-level key of the target table. Keys not listed here are")
    line("accepted and merged as-is.")
    line("")
    line("| key | type |")
    line("|---|---|")
    local keyNames = {}
    for keyName in pairs(spec.keys) do keyNames[#keyNames + 1] = keyName end
    table.sort(keyNames)
    for _, keyName in ipairs(keyNames) do
      line("| `%s` | %s |", keyName, spec.keys[keyName].desc)
    end
  elseif spec.fields then
    line("")
    line("| field | type | required |")
    line("|---|---|---|")
    local fieldNames = {}
    for fieldName in pairs(spec.fields) do fieldNames[#fieldNames + 1] = fieldName end
    table.sort(fieldNames)
    for _, fieldName in ipairs(fieldNames) do
      local ft = spec.fields[fieldName]
      line("| `%s` | %s | %s |", fieldName, ft.desc,
        ft.kind == "opt" and "no" or "yes")
    end
  elseif spec.keyValue then
    line("")
    line("Id = a top-level key of the target table; every key carries the same")
    line("shape.")
    line("")
    line("- value: %s", spec.keyValue.desc)
  elseif spec.value then
    line("- value: %s", spec.value.desc)
  end
  if spec.example then
    line("")
    line("```lua")
    line("%s", spec.example)
    line("```")
  end
  -- prose a registry needs beyond its schema (resolution order, the
  -- guarantees a value carries).  It lives on the spec rather than in the
  -- page because this file is regenerated: hand-written paragraphs in the
  -- output are deleted by the next run.
  if spec.notes then
    line("")
    line("%s", spec.notes)
  end
end

line("")
line("## v1 aliases")
line("")
line("| alias | canonical |")
line("|---|---|")
local aliases = {}
for alias in pairs(Schemas.ALIASES) do aliases[#aliases + 1] = alias end
table.sort(aliases)
for _, alias in ipairs(aliases) do
  line("| `%s` | `%s` |", alias, Schemas.ALIASES[alias])
end

-- a wiki checkout may not have the directory yet; create it before the
-- open so pointing at a fresh clone is not a two-step
local file = io.open(OUT, "w")
if not file then
  os.execute('mkdir -p "' .. outDir:gsub('"', '\\"') .. '"')
  file = assert(io.open(OUT, "w"),
    "cannot write " .. OUT .. " (is the output directory reachable?)")
end
file:write(table.concat(out, "\n") .. "\n")
file:close()
print("wrote " .. OUT)