Add docs

.github/workflows/build-docs.yml

@@ -0,0 +1,14 @@
+name: Build Production Site
+
+on:
+  push:
+    branches: [release/**/**]
+    paths:
+      - '**.md'
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger build
+        run: curl -X POST -d {} "${{ secrets.CLOUDFLARE_BUILD_HOOK }}"

.github/workflows/tests.yml

@@ -1,6 +1,12 @@
 name: tests workflow
 
 on:
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "samples/**"
+      - "**.md"
+
   workflow_call:
     inputs:
       runtime_env:

.gitignore

@@ -173,3 +173,7 @@ fabric.properties
 
 # Generated certificates
 certs/
+
+.temp
+.cache
+node_modules

docs/.eslintignore

@@ -0,0 +1,6 @@
+!.vuepress/
+!.*.js
+.cache/
+.temp/
+node_modules/
+dist/

docs/.eslintrc.cjs

@@ -0,0 +1,13 @@
+module.exports = {
+    root: true,
+    extends: 'vuepress',
+    overrides: [
+        {
+            files: ['*.ts', '*.vue'],
+            extends: 'vuepress-typescript',
+            parserOptions: {
+                project: ['tsconfig.json'],
+            },
+        },
+    ],
+}

docs/.node-version

@@ -0,0 +1 @@
+20

docs/.vuepress/client.ts

@@ -0,0 +1,10 @@
+import type {Router} from "vue-router";
+
+interface ClientConfig {
+    enhance?: (context: {
+        app: any;
+        router: Router;
+        siteData: any;
+    }) => void | Promise<void>;
+    setup?: () => void;
+}

docs/.vuepress/config.ts

@@ -0,0 +1,28 @@
+import { dl } from "@mdit/plugin-dl";
+import viteBundler from "@vuepress/bundler-vite";
+import vueDevTools from 'vite-plugin-vue-devtools'
+import { defineUserConfig } from "vuepress";
+import { hopeTheme } from "vuepress-theme-hope";
+import { themeOptions } from "./configs/theme";
+import { linkCheckPlugin } from "./markdown/linkCheck";
+import { replaceLinkPlugin } from "./markdown/replaceLink";
+
+
+export default defineUserConfig({
+  base: "/",
+  dest: "public",
+  title: "Docs",
+  description: "Event-native database",
+  bundler: viteBundler({ viteOptions: { plugins: [vueDevTools(),], } }),
+  markdown: { importCode: false },
+  extendsMarkdown: md => {
+    md.use(linkCheckPlugin);
+    md.use(replaceLinkPlugin, {
+      replaceLink: (link: string, _) => link
+        .replace("@api", "/api")
+        .replace("@server/", "/server/{version}/")
+    });
+    md.use(dl);
+  },
+  theme: hopeTheme(themeOptions, { custom: true }),
+});

docs/.vuepress/configs/theme.ts

@@ -0,0 +1,36 @@
+import type {ThemeOptions} from "vuepress-theme-hope";
+
+export const themeOptions: ThemeOptions = {
+    logo: "/Kurrent Logo - Plum.svg",
+    logoDark: "/Kurrent Logo - White.svg",
+    docsDir: 'docs',
+    editLink: false,
+    lastUpdated: true,
+    toc: true,
+    repo: "https://github.com/kurrent-io",
+    repoLabel: "GitHub",
+    repoDisplay: true,
+    contributors: false,
+    pure: false,
+    darkmode:"toggle",
+    headerDepth: 3,
+    pageInfo: false,
+    markdown: {
+        figure: true,
+        imgLazyload: true,
+        imgMark: true,
+        imgSize: true,
+        tabs: true,
+        codeTabs: true,
+        component: true,
+        mermaid: true,
+        highlighter: {
+            type: "shiki",
+            themes: {
+                light: "one-light",
+                dark: "one-dark-pro",
+            }
+        }
+    }
+}
+

docs/.vuepress/lib/externalPlaceholders.ts

@@ -0,0 +1,6 @@
+const externalPlaceholders = ["@samples", "@clients"];
+
+export function isKnownPlaceholder(placeholder: string): boolean {
+    const known = externalPlaceholders.find(x => x == placeholder);
+    return known !== undefined;
+}

docs/.vuepress/lib/log.ts

@@ -0,0 +1,12 @@
+export default {
+    error(message: string) {
+        console.log("\x1b[41m%s\x1b[0m", ' ERROR ', `${message}\n`)
+        process.exit(0)
+    },
+    info(message: string) {
+        console.log("\x1b[44m%s\x1b[0m", ' INFO ', `${message}\n`)
+    },
+    success(message: string) {
+        console.log("\x1b[42m\x1b[30m%s\x1b[0m", ' DONE ', `${message}\n`)
+    }
+}

docs/.vuepress/lib/types.ts

@@ -0,0 +1,18 @@
+import type {NavItemOptions, SidebarLinkOptions} from "vuepress-theme-hope";
+
+export interface EsSidebarGroupOptions extends NavItemOptions {
+    group?: string;
+    collapsible?: boolean;
+    title?: string;
+    version?: string;
+    prefix?: string;
+    link?: string;
+    children: EsSidebarItemOptions[] | string[];
+}
+
+export type EsSidebarItemOptions = SidebarLinkOptions | EsSidebarGroupOptions | string;
+export type EsSidebarArrayOptions = EsSidebarItemOptions[];
+export type EsSidebarObjectOptions = Record<string, EsSidebarArrayOptions | "structure">;
+export type EsSidebarOptions = EsSidebarArrayOptions | EsSidebarObjectOptions;
+
+export type ImportedSidebarArrayOptions = EsSidebarGroupOptions[];

docs/.vuepress/lib/version.ts

@@ -0,0 +1,15 @@
+const versionRegex = /v((\d+\.)?(\d+\.)?(\*|\d+))/;
+const nightly = "nightly";
+const v = {
+    isVersion: (v: string) => versionRegex.test(v),
+    parseVersion: (v: string) => versionRegex.exec(v),
+    getVersion: (path: string): string | undefined => {
+        if (path.includes(nightly)) {
+            return nightly;
+        }
+        const ref = path.split("#")[0];
+        const split = ref.split("/");
+        return split.find(x => v.isVersion(x));
+    }
+};
+export default v;

docs/.vuepress/lib/versioning.ts

@@ -0,0 +1,135 @@
+import * as fs from "fs";
+import {path} from 'vuepress/utils';
+import log from "./log";
+import {createRequire} from 'node:module';
+// import references from "../versions.json";
+import type {
+    EsSidebarGroupOptions, EsSidebarObjectOptions,
+    ImportedSidebarArrayOptions
+} from "./types";
+
+interface VersionDetail {
+    version: string,
+    path: string,
+    startPage: string
+}
+
+interface Version {
+    id: string,
+    group: string,
+    basePath: string,
+    versions: VersionDetail[]
+}
+
+const createSidebarItem = (item: EsSidebarGroupOptions, path: string, version: string, group: string): EsSidebarGroupOptions => {
+    const xp = `/${path}/`;
+    let ch = item.children as string[];
+    if (item.collapsible !== undefined) {
+        ch = ch.map(x => !x.startsWith('../') ? '../' + x : x);
+    }
+    const childPath = item.prefix ? `/${path}${item.prefix}` : xp;
+    const children = ch.map(x => x.split(xp).join(""));
+    return {
+        ...item,
+        children: children.map(x => `${childPath}${x}`),
+        prefix: undefined,
+        group,
+        version,
+        text: item.text || item.title || ""
+    }
+}
+
+export class versioning {
+    versions: Version[] = [];
+
+    constructor() {
+        // const require = createRequire(import.meta.url)
+        // references.forEach(p => {
+        //     const fileName = path.resolve(__dirname, p);
+        //     if (fs.existsSync(fileName)) {
+        //         log.info(`Importing versions from ${fileName}`);
+        //         const list: Version[] = require(fileName);
+        //         list.forEach(v => {
+        //             const existing = this.versions.find(x => x.id === v.id);
+        //             if (existing === undefined) {
+        //                 this.versions.push(v);
+        //             } else {
+        //                 existing.versions.push(...v.versions);
+        //             }
+        //         });
+        //     } else {
+        //         log.info(`File ${fileName} doesn't exist, ignoring`);
+        //     }
+        // });
+    }
+
+    get latestSemver(): string {
+        const serverDocs = this.versions.find(v => v.id === "server");
+        if (!serverDocs) {
+            throw new Error("Server docs not found");
+        }
+        return serverDocs.versions[0].path;
+    }
+
+    // latest stable release
+    get latest(): string {
+        const serverDocs = this.versions.find(v => v.id === "server");
+        if (!serverDocs) {
+            throw new Error("Server docs not found");
+        }
+        return `${serverDocs.basePath}/${serverDocs.versions[0].path}`;
+    }
+
+    get all() {
+        return this.versions
+    }
+
+    // Generate a single object that represents all versions from each sidebar
+    getSidebars() {
+        let sidebars: EsSidebarObjectOptions = {};
+        const require = createRequire(import.meta.url);
+
+        this.versions.forEach(version => {
+            version.versions.forEach(v => {
+                const p = `${version.basePath}/${v.path}`;
+                const sidebarPath = path.resolve(__dirname, `../../${p}`);
+                const sidebarBase = path.join(sidebarPath, "sidebar");
+                const sidebarJs = `${sidebarBase}.js`;
+                const sidebarCjs = `${sidebarBase}.cjs`;
+                fs.copyFileSync(sidebarJs, sidebarCjs);
+                log.info(`Importing sidebar from ${sidebarJs}`);
+                const sidebar: ImportedSidebarArrayOptions = require(sidebarCjs);
+                sidebars[`/${p}/`] = sidebar.map(item => createSidebarItem(item, p, v.version, version.group));
+                fs.rmSync(sidebarCjs);
+            });
+        })
+
+        console.log(JSON.stringify(sidebars, null, 2));
+        return sidebars;
+    }
+
+    version(id: string) {
+        const ret = this.versions.find(x => x.id === id);
+        if (ret === undefined) log.error(`Version ${id} not defined`);
+        return ret;
+    }
+
+    // Build dropdown items for each version
+    linksFor(id: string, url?: string) {
+        const links: { text: string, link: string }[] = [];
+        const version = this.version(id);
+        if (version === undefined) return links;
+
+        version.versions.forEach(v => {
+            const path = `${version.basePath}/${v.path}`;
+            const pageUrl = (url ? url : v.startPage ? v.startPage : "");
+            const link = `/${path}/${pageUrl}`;
+            const item = {text: v.version, link: link};
+            links.push(item);
+        });
+
+        return links;
+    }
+}
+
+export const instance: versioning = new versioning();