Docs: a page each, and API references for ipx and the directory laid out like docs.rs (#223)
site/gen.mjs writes them from site/api.mjs, which holds each endpoint and type as the handlers have them, and site/docs.mjs, the guides. A misspelt type in api.mjs fails the build rather than leaving a name that links nowhere. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
212
site/gen.mjs
Normal file
212
site/gen.mjs
Normal file
@@ -0,0 +1,212 @@
|
||||
// The docs pages, into site/dist/docs: the guides in docs.mjs, and an API reference for each
|
||||
// service from api.mjs, laid out as docs.rs lays out a crate (#223): a root page listing its
|
||||
// modules and types, a page a module listing its endpoints, a page an endpoint and a page a type.
|
||||
// No script: the site's Content-Security-Policy allows none of its own.
|
||||
//
|
||||
// node site/gen.mjs (site/build.sh runs it)
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { ipx, directory } from './api.mjs';
|
||||
import { guides } from './docs.mjs';
|
||||
|
||||
const here = path.dirname(fileURLToPath(import.meta.url));
|
||||
const dist = path.join(here, 'dist');
|
||||
const SRC = 'https://git.sdf1.net/rays/ipx/src/branch/main';
|
||||
|
||||
const esc = s => String(s).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
||||
|
||||
/// The version a reference documents: its service's last release, from its changelog, not the
|
||||
/// -dev version between releases.
|
||||
function released(changelog) {
|
||||
const m = fs.readFileSync(path.join(here, '..', changelog), 'utf8').match(/^## \[(\d+\.\d+\.\d+)\]/m);
|
||||
return m ? m[1] : '';
|
||||
}
|
||||
|
||||
function write(rel, html) {
|
||||
const file = path.join(dist, rel);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, html);
|
||||
}
|
||||
|
||||
function shell({ title, description, sidebar, body, current }) {
|
||||
return `<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||||
<title>${esc(title)}</title>
|
||||
<meta name="description" content="${esc(description)}">
|
||||
<meta name="color-scheme" content="light">
|
||||
<link rel="icon" href="/favicon.png">
|
||||
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
|
||||
<link rel="stylesheet" href="/site.css">
|
||||
</head>
|
||||
<body>
|
||||
<header class="bar">
|
||||
<a class="home" href="/"><img src="/logo.svg" alt="" width="36" height="36">iPX</a>
|
||||
<nav aria-label="Elsewhere">
|
||||
<a href="/docs/" aria-current="true">Docs</a>
|
||||
<a href="https://directory.ipxreader.app">Directory</a>
|
||||
<a class="src" href="https://git.sdf1.net/rays/ipx" title="Source code on git.sdf1.net"><img src="/gitea.svg" alt="Source code" width="28" height="28"></a>
|
||||
</nav>
|
||||
</header>
|
||||
<div class="docs">
|
||||
<aside class="side">${sidebar}</aside>
|
||||
<main class="doc">${body}</main>
|
||||
</div>
|
||||
<footer>
|
||||
<p>iPX is free and open source under the MIT licence.</p>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
`;
|
||||
}
|
||||
|
||||
/* ---------------- the guides ---------------- */
|
||||
|
||||
const REFS = [[ipx, 'ipx'], [directory, 'ipx-directory']];
|
||||
|
||||
function guideSidebar(cur) {
|
||||
const li = (href, name, on) => `<li><a href="${href}"${on ? ' aria-current="page"' : ''}>${name}</a></li>`;
|
||||
return `<nav aria-label="Docs">
|
||||
<h2 class="side-h">Guides</h2>
|
||||
<ul>${guides.map(g => li(g.href, g.name, g.href === cur)).join('')}</ul>
|
||||
<h2 class="side-h">API reference</h2>
|
||||
<ul>${REFS.map(([r, label]) => li(r.root + '/', label, false)).join('')}</ul>
|
||||
</nav>`;
|
||||
}
|
||||
|
||||
for (const g of guides) {
|
||||
write(g.file, shell({ title: g.title, description: g.description, sidebar: guideSidebar(g.href), body: g.body, current: 'docs' }));
|
||||
}
|
||||
|
||||
/* ---------------- the references ---------------- */
|
||||
|
||||
const METHOD_CLASS = { GET: 'm-get', POST: 'm-post', PATCH: 'm-patch', PUT: 'm-patch', DELETE: 'm-delete' };
|
||||
|
||||
function reference(api) {
|
||||
const label = api.label || api.name;
|
||||
const version = released(api.changelog);
|
||||
const typeNames = new Set(api.types.map(t => t.name));
|
||||
const typeHref = n => `${api.root}/types/${n}`;
|
||||
const itemHref = (g, it) => `${api.root}/${g.id}/${it.slug}`;
|
||||
const fnName = it => it.slug.replace(/-/g, '_');
|
||||
// A Rust type, its names that are types of this API linked.
|
||||
const ty = s => esc(s).replace(/\b[A-Z][A-Za-z]+\b/g, n => typeNames.has(n) ? `<a class="t" href="${typeHref(n)}">${n}</a>` : n);
|
||||
const isType = s => /^[A-Z]/.test(s) && /[A-Za-z>]$/.test(s) && !/\s/.test(s.replace(/, /g, ','));
|
||||
const access = it => it.access || 'signed in';
|
||||
|
||||
// Which endpoints mention each type, for its "Used by", as docs.rs lists where a type turns up.
|
||||
const usedBy = new Map();
|
||||
for (const g of api.groups) for (const it of g.items) {
|
||||
for (const s of [it.body, it.query, it.returns].filter(Boolean)) {
|
||||
for (const n of s.match(/\b[A-Z][A-Za-z]+\b/g) || []) if (typeNames.has(n)) {
|
||||
if (!usedBy.has(n)) usedBy.set(n, []);
|
||||
if (!usedBy.get(n).some(([, x]) => x === it)) usedBy.get(n).push([g, it]);
|
||||
}
|
||||
}
|
||||
}
|
||||
// Types inside types: a type used only as a field is reached from the type that holds it.
|
||||
for (const t of api.types) for (const [, ft] of t.fields) {
|
||||
for (const n of ft.match(/\b[A-Z][A-Za-z]+\b/g) || []) if (typeNames.has(n) && n !== t.name) {
|
||||
if (!usedBy.has(n)) usedBy.set(n, []);
|
||||
if (!usedBy.get(n).some(([, x]) => x === t)) usedBy.get(n).push([null, t]);
|
||||
}
|
||||
}
|
||||
|
||||
const crumbs = (...parts) => `<p class="path"><a href="${api.root}/">${esc(api.name)}</a>${parts.map(([h, n]) => `::<a href="${h}">${n}</a>`).join('')}</p>`;
|
||||
const top = `<a class="crate" href="${api.root}/"><img src="/logo.svg" alt="" width="40" height="40"><span><b>${esc(label)}</b>${version ? `<span class="ver">${version}</span>` : ''}</span></a>`;
|
||||
const back = `<p class="side-back"><a href="/docs/">All docs</a></p>`;
|
||||
|
||||
function sidebar({ group, item, type } = {}) {
|
||||
let s = top;
|
||||
if (group) {
|
||||
s += `<h2 class="side-h">Module <a href="${api.root}/${group.id}/">${group.name}</a></h2>
|
||||
<ul class="items">${group.items.map(it => `<li><a class="${METHOD_CLASS[it.method]}" href="${itemHref(group, it)}" title="${it.method} ${esc(it.path)}"${it === item ? ' aria-current="page"' : ''}><span class="verb">${it.method}</span> ${fnName(it)}</a></li>`).join('')}</ul>`;
|
||||
}
|
||||
s += `<h2 class="side-h">Modules</h2><ul>${api.groups.map(g => `<li><a href="${api.root}/${g.id}/"${g === group && !item ? ' aria-current="page"' : ''}>${g.name}</a></li>`).join('')}</ul>`;
|
||||
s += `<h2 class="side-h">Types</h2><ul class="types">${api.types.map(t => `<li><a class="t" href="${typeHref(t.name)}"${t === type ? ' aria-current="page"' : ''}>${t.name}</a></li>`).join('')}</ul>`;
|
||||
return `<nav aria-label="${esc(label)} reference">${s}</nav>${back}`;
|
||||
}
|
||||
|
||||
const page = (rel, title, description, side, body) =>
|
||||
write(rel, shell({ title, description, sidebar: side, body, current: 'docs' }));
|
||||
|
||||
// The root: what the crate page shows on docs.rs, its modules and types.
|
||||
page(`${api.root.slice(1)}/index.html`, `${label} API`, `The HTTP API of ${label}, endpoint by endpoint.`, sidebar(),
|
||||
`<h1 class="item"><span class="kind">API</span> <span class="name">${esc(label)}</span>${version ? ` <span class="ver">${version}</span>` : ''}</h1>
|
||||
${api.intro}
|
||||
<h2 id="modules">Modules</h2>
|
||||
<dl class="list">${api.groups.map(g => `<dt><a href="${api.root}/${g.id}/">${g.name}</a></dt><dd>${g.summary}</dd>`).join('')}</dl>
|
||||
<h2 id="types">Types</h2>
|
||||
<dl class="list">${api.types.map(t => `<dt><a class="t" href="${typeHref(t.name)}">${t.name}</a></dt><dd>${t.doc || ''}</dd>`).join('')}</dl>`);
|
||||
|
||||
for (const g of api.groups) {
|
||||
page(`${api.root.slice(1)}/${g.id}/index.html`, `${api.name}::${g.name}`, g.title, sidebar({ group: g }),
|
||||
`${crumbs()}<h1 class="item"><span class="kind">Module</span> ${esc(api.name)}::<span class="name">${g.name}</span></h1>
|
||||
<p>${g.summary}</p>
|
||||
<h2 id="endpoints">Endpoints</h2>
|
||||
<dl class="list">${g.items.map(it => `<dt><a class="${METHOD_CLASS[it.method]}" href="${itemHref(g, it)}"><span class="verb">${it.method}</span> ${esc(it.path)}</a></dt><dd>${it.summary}</dd>`).join('')}</dl>`);
|
||||
|
||||
for (const it of g.items) {
|
||||
const decl = [
|
||||
`<span class="verb ${METHOD_CLASS[it.method]}">${it.method}</span> ${esc(it.path)}`,
|
||||
it.query && ` query ${ty(it.query)}`,
|
||||
it.body && ` body ${ty(it.body)}`,
|
||||
` -> ${isType(it.returns) ? ty(it.returns) : esc(it.returns)}`,
|
||||
].filter(Boolean).join('\n');
|
||||
const fieldsOf = n => api.types.find(t => t.name === n)?.fields || [];
|
||||
const rows = list => `<dl class="fields">${list.map(([n, t, d]) => `<dt id="${it.slug}-${n}"><code>${esc(n)}: ${ty(t)}</code></dt><dd>${d || ''}</dd>`).join('')}</dl>`;
|
||||
let body = `${crumbs([`${api.root}/${g.id}/`, g.name])}
|
||||
<h1 class="item"><span class="kind">Endpoint</span> ${esc(api.name)}::${g.name}::<span class="name fn">${fnName(it)}</span><a class="srclink" href="${SRC}/${api.name === 'ipx' ? 'crates/ipx/src/web.rs' : 'crates/directory/src/lib.rs'}">Source</a></h1>
|
||||
<pre class="decl"><code>${decl}</code></pre>
|
||||
<p class="summary">${it.summary}</p>
|
||||
${it.doc || ''}
|
||||
<p class="access">Access: <b>${esc(access(it))}</b></p>`;
|
||||
if (it.pathParams) body += `<h2>Path parameters</h2>${rows(it.pathParams)}`;
|
||||
if (it.query) body += `<h2>Query</h2><p>${ty(it.query)}, as query parameters:</p>${rows(fieldsOf(it.query))}`;
|
||||
if (it.body) body += `<h2>Body</h2><p>${ty(it.body)}, as JSON.</p>`;
|
||||
body += `<h2>Returns</h2><p>${isType(it.returns) ? `${ty(it.returns)}, as JSON.` : esc(it.returns)}</p>`;
|
||||
if (it.errors?.length) body += `<h2>Errors</h2><dl class="fields">${it.errors.map(([c, d]) => `<dt><code>${esc(c)}</code></dt><dd>${d}</dd>`).join('')}</dl>`;
|
||||
if (it.example) body += `<h2>Example</h2><pre><code>${esc(it.example)}</code></pre>`;
|
||||
page(`${api.root.slice(1)}/${g.id}/${it.slug}.html`, `${it.method} ${it.path} - ${label}`, it.summary.replace(/<[^>]+>/g, ''), sidebar({ group: g, item: it }), body);
|
||||
}
|
||||
}
|
||||
|
||||
page(`${api.root.slice(1)}/types/index.html`, `${api.name}::types`, `The types ${label}'s API takes and gives.`, sidebar(),
|
||||
`${crumbs()}<h1 class="item"><span class="kind">Module</span> ${esc(api.name)}::<span class="name">types</span></h1>
|
||||
<dl class="list">${api.types.map(t => `<dt><a class="t" href="${typeHref(t.name)}">${t.name}</a></dt><dd>${t.doc || ''}</dd>`).join('')}</dl>`);
|
||||
|
||||
for (const t of api.types) {
|
||||
const decl = t.name === 'Event'
|
||||
? `enum Event {\n${t.fields.map(([n, f]) => ` ${n} ${ty(f)},`).join('\n')}\n}`
|
||||
: t.fields.length
|
||||
? `struct ${t.name} {\n${t.fields.map(([n, f]) => ` ${n}: ${ty(f)},`).join('\n')}\n}`
|
||||
: `enum ${t.name}`;
|
||||
const uses = usedBy.get(t.name) || [];
|
||||
let body = `${crumbs([`${api.root}/types/`, 'types'])}
|
||||
<h1 class="item"><span class="kind">${t.name === 'Event' || !t.fields.length ? 'Enum' : 'Struct'}</span> ${esc(api.name)}::types::<span class="name t">${t.name}</span></h1>
|
||||
<pre class="decl"><code>${decl}</code></pre>
|
||||
${t.doc ? `<p class="summary">${t.doc}</p>` : ''}`;
|
||||
if (t.fields.length) {
|
||||
body += `<h2>${t.name === 'Event' ? 'Variants' : 'Fields'}</h2><dl class="fields">${t.fields.map(([n, f, d]) =>
|
||||
`<dt id="${n}"><a class="anchor" href="#${n}" aria-label="Link to ${esc(n)}">§</a><code>${esc(n)}${t.name === 'Event' ? ' ' : ': '}${ty(f)}</code></dt><dd>${d || ''}</dd>`).join('')}</dl>`;
|
||||
}
|
||||
if (uses.length) {
|
||||
body += `<h2>Used by</h2><ul class="uses">${uses.map(([g, x]) => g
|
||||
? `<li><a class="${METHOD_CLASS[x.method]}" href="${itemHref(g, x)}"><span class="verb">${x.method}</span> ${esc(x.path)}</a></li>`
|
||||
: `<li><a class="t" href="${typeHref(x.name)}">${x.name}</a></li>`).join('')}</ul>`;
|
||||
}
|
||||
page(`${api.root.slice(1)}/types/${t.name}.html`, `${t.name} - ${label}`, (t.doc || `${t.name} in ${label}'s API`).replace(/<[^>]+>/g, ''), sidebar({ type: t }), body);
|
||||
}
|
||||
|
||||
// Every link to a type must name one there is: a misspelt type in api.mjs is otherwise a
|
||||
// name in plain text, which looks right and leads nowhere.
|
||||
for (const g of api.groups) for (const it of g.items) for (const s of [it.body, it.query].filter(Boolean)) {
|
||||
for (const n of s.match(/\b[A-Z][A-Za-z]+\b/g)) if (!typeNames.has(n) && !['Vec', 'Option'].includes(n)) throw new Error(`${it.path}: no type ${n}`);
|
||||
}
|
||||
}
|
||||
|
||||
reference(ipx);
|
||||
reference(directory);
|
||||
Reference in New Issue
Block a user