NEXT: Automated Documentation

[endigo9740]

This will act as a hub to centralize this information.

Goal

We need to determine a framework-agnostic solution to retrieve and document props, events, and children within each component. This will replace our Svelte-only option used in previous versions of Skeleton, called Sveld.

Solutions

Svelte:

• extractinator - we're awaiting this for Svelte 5 support.

React:

• YousefED/typescript-json-schema - we're moving forward with this for now.
• vega/ts-json-schema-generator - a more modern fork we'll migrate to in the future.

Not Used:

• vite-plugin-type-to-schema
• https://www.npmjs.com/package/espree
• https://typedoc.org/
• https://github.com/ghostdevv/extractinator
• https://github.com/HiDeoo/starlight-typedoc

Todo

• Create a prototype using Astro and a simple test component and type
• Create a reusable doc component to scaffold an API block on demand
• Test implementation with the Avatar component
• Update contribution instructions

Feedback

If you have additional updates or requests for this feature, please do so in the comments section below.

[endigo9740]

Sharing this for future reference. @Hugos68 implemented a programmatic way to generate schema via a custom Node script using vega/ts-json-schema-generator. Which is a more modern fork than we're using atm. While super cool, this is probably overkill for the time being. It's also blocked by this PR, which is preventing Windows users at the moment.

import glob from "fast-glob";
import { join } from "path";
import { createGenerator } from "ts-json-schema-generator";
import { promises as fs } from "fs";
import { performance } from "perf_hooks";

/**
 *    Generate schema for a ts file
 * @param {string} path
 * @returns {ReturnType<ReturnType<typeof createGenerator>['createSchema']>}
 */
function generate_schema(path) {
    /** @type {import('ts-json-schema-generator/dist/src/Config').Config} */
    const config = {
        path,
        type: "*",
        skipTypeCheck: true,
    };
    const generator = createGenerator(config);
    const schema = generator.createSchema(config.type);
    return schema;
}

/**
 * @param configuration Configuration object
 * @param configuration.matcher The glob pattern to match the files.
 * @param configuration.output_name The name of the output schema file.
 */
async function main({ matcher, output_name }) {
    /**
     * @type {Array<Promise<void>>}
     */
    const promises = [];
    const files = await glob(matcher);
    for (const file of files) {
        const promise = new Promise((resolve) => {
            const start = performance.now();
            const file_path = join(import.meta.dirname, file);
            const schema_path = file_path.replace("types.ts", output_name);
            const schema = generate_schema(file_path);
            fs.writeFile(schema_path, JSON.stringify(schema, null, 2)).then(() => {
                const end = performance.now();
                console.log(`Schema generated for: "${file_path}"
Schema saved at: "${schema_path}"
Time taken: ${(end - start).toFixed("2")}ms
`);
                resolve();
            });
        });
        promises.push(promise);
    }
    await Promise.all(promises);
}

await main({
    matcher: "**/src/components/**/types.ts",
    output_name: "schema.json",
});

[endigo9740]

Just a quick update for this...

We've now implemented support for React component auto-docs via:
https://github.com/YousefED/typescript-json-schema?tab=readme-ov-file

This allows for everything but automatically fetching the default value. A new table component has been introduced to display the schema information per all existing component pages.

In the future, we'll revisit this to handle Svelte 5, likely using:
https://github.com/ghostdevv/extractinator

We'll also look at migrating React to following tool, or whatever solution allows us to populate the default values:
https://github.com/vega/ts-json-schema-generator

This tool operates in a similar manner, but is a more recent "fork" with some improvements.