Merge pull request #21 from thegreenwebfoundation/tc-schema-docs-generation

Automatically generate html schema docs

Author: timcowlishaw

.github/workflows/jekyll.yml

@@ -28,6 +28,8 @@ jobs:
           ruby-version: '3.3'
           bundler-cache: true
 
+      - run: npm run schema-to-data
+
       - run: bundle exec jekyll build
 
       - uses: actions/upload-pages-artifact@v4

_data/generated/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

_includes/schema-table.html

@@ -0,0 +1,57 @@
+{% assign s = include.schema %}
+
+<section class="schema-doc">
+  {% if s.title %}<h2>{{ s.title }}</h2>{% endif %}
+  {% if s.description %}<p>{{ s.description }}</p>{% endif %}
+
+  <table>
+    <thead>
+      <tr>
+        <th>Property</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      {% for prop in s.properties %}
+      <tr>
+        <td><code>{{ prop.name }}</code></td>
+        <td>
+          <code>{{ prop.type }}</code>
+          {% if prop.type == 'array' and prop.items %}
+            of <code>{{ prop.items.type }}</code>
+          {% endif %}
+        </td>
+        <td>{% if prop.required %}✓{% endif %}</td>
+        <td>{% if prop.default != nil %}<code>{{ prop.default }}</code>{% endif %}</td>
+        <td>
+          {{ prop.description }}
+
+          {% if prop.enum %}
+            <br>One of:
+            {% for v in prop.enum %}<code>{{ v }}</code>{% unless forloop.last %}, {% endunless %}{% endfor %}
+          {% endif %}
+
+          {% if prop.type == 'object' and prop.properties %}
+            {% include schema-table.html schema=prop %}
+          {% endif %}
+
+          {% if prop.type == 'array' and prop.items.properties %}
+            Items:
+            {% include schema-table.html schema=prop.items %}
+          {% endif %}
+
+          {% if prop.variants %}
+            <em>{{ prop.type }}:</em>
+            {% for variant in prop.variants %}
+              <strong>{{ variant.name }}</strong>
+              {% if variant.description %} — {{ variant.description }}{% endif %}
+              {% if variant.properties %}
+                {% include schema-table.html schema=variant %}
+              {% endif %}
+            {% endfor %}
+          {% endif %}
+        </td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</section>

package-lock.json

@@ -1,5 +1,9 @@
 {
+  "scripts": {
+    "schema-to-data": "node scripts/schema-to-data.js schema/dist/dist-v0.0.1.json _data/generated/schema.json"
+  },
   "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^15.4.0",
     "@tailwindcss/aspect-ratio": "^0.4.2",
     "@tailwindcss/forms": "^0.5.11",
     "@tailwindcss/line-clamp": "^0.4.4",

package.json

@@ -34,11 +34,11 @@ The schema is metrics-focused and aligns with the [DIST taxonomy](/taxonomy). Mo
 
 ### This IS NOT:
 
-* A prescriptive methodology - the schema defines what to report, not how to calculate it; recommended methodologies will be available through the [DIST methodology map](/methodologies) but are not required. 
+* A prescriptive methodology - the schema defines what to report, not how to calculate it; recommended methodologies will be available through the [DIST methodology map](/methodologies) but are not required.
 
 * A certification or compliance framework - though it should be useful for those who need to comply with regulations like CSRD.
 
-* A commercial product - it is open source, dual-licensed for open adoption and ISO standardisation but it is commercial product friendly - it can be used in commercial products and services. 
+* A commercial product - it is open source, dual-licensed for open adoption and ISO standardisation but it is commercial product friendly - it can be used in commercial products and services.
 
 ## Use cases: what will people actually do with this?
 
@@ -58,4 +58,8 @@ Benchmark and compare. Because the schema enforces a consistent structure, repor
 **Campaign and hold to account.** An NGO, journalist, or activist uses published schema data to identify organisations with poor performance on specific dimensions (e.g. e-waste, societal harms) and make evidence-based cases for improvement. Machine-readable data is far harder to hide behind than a glossy sustainability report.
 
 **Build tools and services.** Developers build calculators, dashboards, benchmarking platforms, and analysis tools on top of the schema. Because the data structure is open and consistent, tooling built for one organisation works for any organisation. The schema becomes infrastructure that an ecosystem of tools plugs into.
-Teach and learn. Educators, training providers, and professional bodies use the taxonomy as a teaching framework for technology sustainability that goes beyond carbon. The dimensions provide a structured syllabus for understanding the full breadth of technology's impacts.
+Teach and learn. Educators, training providers, and professional bodies use the taxonomy as a teaching framework for technology sustainability that goes beyond carbon. The dimensions provide a structured syllabus for understanding the full breadth of technology's impacts.
+
+
+{% include schema-table.html schema=site.data.generated.schema %}
+

schema.markdown

@@ -0,0 +1,84 @@
+import $RefParser from '@apidevtools/json-schema-ref-parser';
+import { writeFileSync } from 'fs';
+import { basename, extname } from 'path';
+
+const inputFile = process.argv[2];
+const outputFile = process.argv[3]
+
+if (!inputFile || !outputFile) {
+  console.error('Usage: node scripts/schema-to-data.js <inputPath> <outputPath>');
+  process.exit(1);
+}
+
+function processProperty(name, prop, required = []) {
+  const base = {
+    name,
+    required: required.includes(name),
+    description: prop.description || '',
+    default: prop.default ?? null,
+    enum: prop.enum || null,
+    properties: null,
+    variants: null,
+  };
+
+  if (prop.type && prop.type !== 'object') {
+    return { ...base, type: prop.type };
+  }
+
+  if (prop.type === 'object' || prop.properties) {
+    return {
+      ...base,
+      type: 'object',
+      properties: processSchema(prop),
+    };
+  }
+
+  if (prop.type === 'array' && prop.items) {
+    const items = prop.items;
+    return {
+      ...base,
+      type: 'array',
+      items: items.properties
+        ? { type: 'object', properties: processSchema(items) }
+        : { type: items.type || 'any' },
+    };
+  }
+
+  const combiner = ['anyOf', 'oneOf', 'allOf'].find(k => prop[k]);
+  if (combiner) {
+    return {
+      ...base,
+      type: combiner,
+      variants: prop[combiner].map((variant, i) => ({
+        name: variant.title || `Option ${i + 1}`,
+        description: variant.description || '',
+        type: variant.type || 'object',
+        properties: variant.properties ? processSchema(variant) : null,
+      })),
+    };
+  }
+
+  return { ...base, type: 'any' };
+}
+
+function processSchema(schema) {
+  return Object.entries(schema.properties || {}).map(([name, prop]) =>
+    processProperty(name, prop, schema.required || [])
+  );
+}
+
+try {
+  const schema = await $RefParser.dereference(inputFile);
+
+  const data = {
+    title: schema.title || '',
+    description: schema.description || '',
+    properties: processSchema(schema),
+  };
+
+  writeFileSync(outputFile, JSON.stringify(data, null, 2));
+  console.log(`Written to ${outputFile}`);
+} catch (err) {
+  console.error('Failed to process schema:', err.message);
+  process.exit(1);
+}