docs: start refgen v2

Author: znotfireman

.lute/refgen.luau

@@ -0,0 +1,7 @@
+local docs = require("@config/docs")
+local path = require("@std/path")
+
+return {
+	libraries = path.join(docs.directory, docs.documentationPaths.libraries),
+	mechanics = path.join(docs.directory, docs.documentationPaths.mechanics),
+}

.lute/refgen/filepaths.luau

@@ -0,0 +1,52 @@
+local pp = require("@batteries/pp")
+local docs = require("@config/docs")
+local project = require("@config/project")
+local clearDirectory = require("@scripts/lib/clearDirectory")
+local text = require("@scripts/lib/text")
+local filepaths = require("@self/filepaths")
+local moonwaveModel = require("@self/moonwaveModel")
+local process = require("@std/process")
+local json = require("@std/json")
+local moonwave = require("@self/moonwave")
+local templates = require("@self/templates")
+local fs = require("@std/fs")
+local path = require("@std/path")
+
+local raw = process.run({
+	"moonwave-extractor",
+	"extract",
+	project.source,
+}).stdout
+
+local model = moonwaveModel(json.deserialize(raw) :: moonwave.Extracted)
+
+clearDirectory(filepaths.libraries)
+
+local libraryNav: { { [string]: { string } } } = {}
+
+for _, library in model.libraries do
+	local libraryContents = templates.Library:gsub("{(.-)}", library :: { [string]: string })
+
+	local hyperlink = model.nameToHyperlinks[library.name]
+	model.nameToHyperlinks[library.name] = nil
+	libraryContents = libraryContents:gsub("%w*", model.nameToHyperlinks)
+	model.nameToHyperlinks[library.name] = hyperlink
+
+	local index = path.join(library.outputDirectory, "index.md")
+	print("Writing library", library.name)
+	fs.createdirectory(library.outputDirectory, { makeparents = true })
+	fs.writestringtofile(index, libraryContents)
+
+	table.insert(libraryNav, { [library.name] = { path.format(index) } })
+end
+
+local zensical = fs.readfiletostring(docs.zensical)
+zensical = text.replaceSectionedBlock(
+	zensical,
+	-- json is close enough lmao
+	-- + toml breaks anyway
+	json.serialize(libraryNav :: any):gsub(":", "="),
+	"# refgen: libraries start",
+	"# refgen: libraries end"
+)
+fs.writestringtofile(docs.zensical, zensical)

.lute/refgen/init.luau

@@ -0,0 +1,83 @@
+local docs = require("@config/docs")
+local project = require("@config/project")
+local text = require("@scripts/lib/text")
+local reconstructRequirePath = require("./reconstructRequirePath")
+local sourcemap = require("./sourcemap")
+local path = require("@std/path")
+local filepaths = require("./filepaths")
+local moonwave = require("./moonwave")
+
+export type Library = {
+	name: string,
+	slug: string,
+	summary: string,
+	description: string,
+
+	sourcePath: string,
+	sourceLine: number,
+	importPath: string,
+
+	outputDirectory: path.path,
+	outputUrl: path.path,
+}
+
+export type Mechanic = {}
+
+export type Model = {
+	libraries: { Library },
+	mechanics: { Mechanic },
+	sourcemapPaths: { [string]: { string } },
+	nameToUrls: { [string]: string },
+	nameToHyperlinks: { [string]: string },
+}
+
+local function modelLibrary(model: Model, library: moonwave.Class): Library
+	local sourcePath = project.source .. "/" .. library.source.path
+	local slug = string.lower(library.name)
+	local url = path.join(docs.documentationPaths.libraries, slug)
+	model.nameToUrls[library.name] = path.format(url)
+	model.nameToHyperlinks[library.name] = `<a href={text.quote("/" .. path.format(url))}>{library.name}</a>`
+
+	return {
+		name = library.name,
+		slug = slug,
+		summary = string.match(library.desc, "^[^\n]+") or "",
+		description = library.desc,
+
+		sourcePath = sourcePath,
+		sourceLine = library.source.line,
+		importPath = table.concat(
+			reconstructRequirePath(model.sourcemapPaths, sourcePath)
+				or error(`library {library.source.path} cannot be imported`),
+			"/"
+		),
+
+		outputDirectory = path.join(filepaths.libraries, slug),
+		outputUrl = url,
+	}
+end
+
+local function moonwaveModel(classes: { moonwave.Class })
+	local model: Model = {
+		libraries = {},
+		mechanics = {},
+		sourcemapPaths = sourcemap.process(),
+		nameToUrls = {},
+		nameToHyperlinks = {},
+	}
+
+	for _, class in ipairs(classes) do
+		local tags: { string } = class.tags or {}
+
+		for _, tag in tags do
+			if tag == "Library" then
+				table.insert(model.libraries, modelLibrary(model, class))
+				break
+			end
+		end
+	end
+
+	return model
+end
+
+return moonwaveModel

.lute/lib/moonwave.luau .lute/refgen/moonwave.luau.lute/lib/moonwave.luau renamed to .lute/refgen/moonwave.luau

@@ -0,0 +1,31 @@
+local path = require("@std/path")
+
+local function reconstructRequirePath(sourcemapPaths: { [string]: { string } }, inputPath: string): { string }?
+	local bestSource, bestLen = "", 0
+	for sourcePath in sourcemapPaths do
+		if string.find(inputPath, "^" .. sourcePath) then
+			local len = string.len(sourcePath)
+			if bestLen < len then
+				bestSource, bestLen = sourcePath, len
+			end
+		end
+	end
+
+	if bestLen == 0 then
+		return nil
+	end
+
+	local requirePath = table.clone(sourcemapPaths[bestSource])
+	if requirePath[1] == "game" then
+		requirePath[1] = "@game"
+	end
+
+	local sourceParts = path.parse(bestSource).parts
+	local parts = path.parse(inputPath).parts
+	local lenParts = #parts
+	parts[lenParts] = string.match(parts[lenParts], "(.+)%..+$")
+	table.move(parts, #sourceParts + 1, #parts, #requirePath + 1, requirePath)
+	return requirePath
+end
+
+return reconstructRequirePath

.lute/refgen/moonwaveModel.luau

@@ -0,0 +1,41 @@
+local project = require("@config/project")
+local fs = require("@std/fs")
+local json = require("@std/json")
+
+type ProjectPath = string | { optional: string }
+type ProjectNode = { [string]: ProjectNode, ["$path"]: ProjectPath? }
+type Project = { tree: ProjectNode }
+
+local BLACKLISTED_NAMES = {
+	["$className"] = true,
+	["$path"] = true,
+	["$properties"] = true,
+}
+
+local function processNode(node: ProjectNode, paths: { [string]: { string } }, currentPath: { string })
+	local nodePath = node["$path"]
+	if nodePath then
+		nodePath = type(nodePath) == "string" and nodePath or nodePath.optional
+		paths[nodePath] = table.clone(currentPath)
+	end
+
+	for name, child in node do
+		if not BLACKLISTED_NAMES[name] and type(child) == "table" then
+			local newPath = table.clone(currentPath)
+			table.insert(newPath, name)
+			processNode(child, paths, newPath)
+		end
+	end
+end
+
+local function process()
+	local sourcemapProject = json.deserialize(fs.readfiletostring(project.rojoProjects.sourcemap)) :: Project
+	local sourcemapPaths = {}
+	processNode(sourcemapProject.tree, sourcemapPaths, { "game" })
+	return sourcemapPaths
+end
+
+return {
+	processNode = processNode,
+	process = process,
+}

.lute/refgen/reconstructRequirePath.luau

@@ -0,0 +1,7 @@
+return [[<div class="wth-api-item">
+    <span class="wth-api-symbol">{apiSymbol}</span>
+    <a href="{url}" class="wth-api-content">
+        <span class="wth-api-header">{name}</span>
+        <p>{summary}</p>
+    </a>
+<div>]]

.lute/refgen/sourcemap.luau

@@ -0,0 +1,3 @@
+return [[<div class="wth-api-list">
+    {api}
+</div>]]

.lute/refgen/templates/ApiItem.luau

@@ -0,0 +1,19 @@
+return [[{header}
+
+# <span class="wth-ref-header-function">function</span> {name}
+
+```luau
+{signature}
+```
+
+{desc}
+
+## Parameters
+
+{parameters}
+
+## Returns
+
+{returns}
+
+]]