docs: render isometric peripheral blocks

projects/typed-peripheral-digitalitems/documentation/generate-docs.mjs

@@ -96,6 +96,17 @@ function escapeCell(value) {
   return value.replaceAll("|", "\\|").replaceAll("\n", " ");
 }
 
+async function renderBlock(textureRoot, block) {
+  const texture = async (face) => (await readFile(resolve(textureRoot, `${block}_${face}.png`))).toString("base64");
+  const [side, front, top] = await Promise.all([texture("side"), texture("front_on"), texture("top")]);
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <polygon points="12,83 64,113 116,83 64,53" fill="#000" opacity=".28"/>
+  <image href="data:image/png;base64,${side}" width="16" height="16" image-rendering="pixelated" transform="matrix(3 1.5 0 3 16 32)"/>
+  <image href="data:image/png;base64,${front}" width="16" height="16" image-rendering="pixelated" transform="matrix(3 -1.5 0 3 64 56)"/>
+  <image href="data:image/png;base64,${top}" width="16" height="16" image-rendering="pixelated" transform="matrix(3 1.5 -3 1.5 64 8)"/>
+</svg>\n`;
+}
+
 export function renderPeripheral(peripheral, revision = "") {
   const lines = [
     "## Peripheral methods",
@@ -104,11 +115,9 @@ export function renderPeripheral(peripheral, revision = "") {
     "",
   ];
   for (const method of peripheral.methods) {
-    lines.push(`### \`${method.name}\``, "");
-    if (method.inheritedFrom) lines.push(`*Inherited from \`${method.inheritedFrom}\`.*`, "");
-    for (const [index, signature] of method.signatures.entries()) {
-      if (method.signatures.length > 1) lines.push(`#### Overload ${index + 1}`, "");
-      lines.push("```typescript", signature.signature, "```", "");
+    for (const signature of method.signatures) {
+      lines.push(`### \`${signature.signature}\``, "");
+      if (method.inheritedFrom) lines.push(`*Inherited from \`${method.inheritedFrom}\`.*`, "");
       if (signature.summary) lines.push(signature.summary, "");
       if (signature.parameters.length) {
         lines.push("| Parameter | Type | Description |", "| --- | --- | --- |");
@@ -149,8 +158,9 @@ export async function buildDocs(args = []) {
   });
   await mkdir(resolve(buildRoot, "assets/peripherals"), { recursive: true });
   const textureRoot = resolve(projectRoot, "../core/src/main/resources/assets/digitalitems/textures/block");
-  await cp(resolve(textureRoot, "digitizer_front_on.png"), resolve(buildRoot, "assets/peripherals/digitizer.png"));
-  await cp(resolve(textureRoot, "advanced_digitizer_front_on.png"), resolve(buildRoot, "assets/peripherals/advanced_digitizer.png"));
+  for (const block of ["digitizer", "advanced_digitizer"]) {
+    await writeFile(resolve(buildRoot, "assets/peripherals", `${block}.svg`), await renderBlock(textureRoot, block));
+  }
   await mkdir(resolve(buildRoot, "assets/stylesheets"), { recursive: true });
   await mkdir(resolve(buildRoot, "assets/javascripts"), { recursive: true });
   await cp(resolve(projectRoot, "documentation/theme/digitalitems.css"), resolve(buildRoot, "assets/stylesheets/digitalitems.css"));

projects/typed-peripheral-digitalitems/documentation/generate-docs.test.mjs

@@ -19,7 +19,10 @@ test("extracts direct, inherited, and generic digitizer methods", () => {
   assert.equal(peripheral.methods.length, 15);
   assert.match(peripheral.methods.find(({ name }) => name === "getConfiguration").signatures[0].signature, /DigitizerConfiguration/);
   assert.equal(peripheral.methods.find(({ name }) => name === "size").inheritedFrom, "InventoryViewAPI");
-  assert.match(renderPeripheral(peripheral), /\*\*Throws:\*\* A Lua error if the slot is empty/);
+  const markdown = renderPeripheral(peripheral);
+  assert.match(markdown, /\*\*Throws:\*\* A Lua error if the slot is empty/);
+  assert.match(markdown, /### `getConfiguration\(\): DigitizerConfiguration`/);
+  assert.doesNotMatch(markdown, /```typescript/);
 });
 
 test("preserves advanced digitizer overloads and nullable tuple unions", () => {

projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md

@@ -5,7 +5,7 @@ peripheralInterface: AdvancedDigitizer
 # Advanced Digitizer
 
 <div class="di-peripheral-hero di-peripheral-hero--advanced">
-  <div class="di-peripheral-image"><img src="../../assets/peripherals/advanced_digitizer.png" alt="Advanced digitizer block" /></div>
+  <div class="di-peripheral-image"><img src="../../assets/peripherals/advanced_digitizer.svg" alt="Advanced digitizer block" /></div>
   <div><span class="di-eyebrow">MULTI-STORAGE PERIPHERAL</span><p>The advanced digitizer moves items, fluids, and energy between attached storage and durable digital identifiers.</p><dl><div><dt>Peripheral type</dt><dd><code>{{ peripheralType }}</code></dd></div><div><dt>Storage</dt><dd>Items, fluids, energy</dd></div><div><dt>Failure style</dt><dd>Recoverable result pairs</dd></div></dl></div>
 </div>
 

projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md

@@ -5,7 +5,7 @@ peripheralInterface: Digitizer
 # Basic Digitizer
 
 <div class="di-peripheral-hero">
-  <div class="di-peripheral-image"><img src="../../assets/peripherals/digitizer.png" alt="Digitizer block" /></div>
+  <div class="di-peripheral-image"><img src="../../assets/peripherals/digitizer.svg" alt="Digitizer block" /></div>
   <div><span class="di-eyebrow">ITEM PERIPHERAL</span><p>The basic digitizer turns physical item stacks into portable digital identifiers and restores them through its internal inventory.</p><dl><div><dt>Peripheral type</dt><dd><code>{{ peripheralType }}</code></dd></div><div><dt>Storage</dt><dd>Items</dd></div><div><dt>Failure style</dt><dd>Lua errors</dd></div></dl></div>
 </div>
 

projects/typed-peripheral-digitalitems/documentation/index.md

@@ -8,11 +8,11 @@ TypeScript with TypeScriptToLua.
 
 <div class="di-peripheral-grid">
   <a class="di-peripheral-card" href="guides/basic-digitizer/">
-    <span class="di-peripheral-image"><img src="assets/peripherals/digitizer.png" alt="Digitizer block" /></span>
+    <span class="di-peripheral-image"><img src="assets/peripherals/digitizer.svg" alt="Digitizer block" /></span>
     <span class="di-peripheral-copy"><strong>Digitizer</strong><small>Peripheral type: <code>digitizer</code></small><span>Digitize and restore items through a simple internal inventory.</span><b>Open peripheral guide &rarr;</b></span>
   </a>
   <a class="di-peripheral-card di-peripheral-card--advanced" href="guides/advanced-items/">
-    <span class="di-peripheral-image"><img src="assets/peripherals/advanced_digitizer.png" alt="Advanced digitizer block" /></span>
+    <span class="di-peripheral-image"><img src="assets/peripherals/advanced_digitizer.svg" alt="Advanced digitizer block" /></span>
     <span class="di-peripheral-copy"><strong>Advanced Digitizer</strong><small>Peripheral type: <code>advanced_digitizer</code></small><span>Move items, fluids, and energy between remote storage and digital IDs.</span><b>Open peripheral guide &rarr;</b></span>
   </a>
 </div>