feat: Added compiled files to repo

.gitignore

@@ -1,4 +1,2 @@
 node_modules
-src/*.d.ts
-src/*.js
 /index.js

src/front-matter.d.ts

@@ -0,0 +1,31 @@
+import { RendererComponent } from 'typedoc/dist/lib/output/components';
+import { PageEvent } from 'typedoc/dist/lib/output/events';
+import { Sidebar } from './types';
+export interface FrontMatterVars {
+    [key: string]: string | number | boolean;
+}
+/**
+ * Prepends YAML block to a string
+ * @param contents - the string to prepend
+ * @param vars - object of required front matter variables
+ */
+export declare const prependYAML: (contents: string, vars: FrontMatterVars) => string;
+/**
+ * Returns the page title as rendered in the document h1(# title)
+ * @param page
+ */
+export declare const getPageTitle: (page: PageEvent) => any;
+export declare class FrontMatterComponent extends RendererComponent {
+    out: string;
+    sidebar: Sidebar;
+    globalsTitle: string;
+    readmeTitle: string;
+    entryDocument: string;
+    globalsFile: string;
+    initialize(): void;
+    onPageEnd(page: PageEvent): void;
+    getYamlItems(page: PageEvent): any;
+    getSidebarLabel(page: PageEvent): any;
+    getId(page: PageEvent): string;
+    getTitle(page: PageEvent): any;
+}

src/front-matter.js

@@ -0,0 +1,123 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrontMatterComponent = exports.getPageTitle = exports.prependYAML = void 0;
+const path = require("path");
+const typedoc_1 = require("typedoc");
+const components_1 = require("typedoc/dist/lib/converter/components");
+const components_2 = require("typedoc/dist/lib/output/components");
+const events_1 = require("typedoc/dist/lib/output/events");
+const reflection_title_1 = require("typedoc-plugin-markdown/dist/resources/helpers/reflection-title");
+/**
+ * Prepends YAML block to a string
+ * @param contents - the string to prepend
+ * @param vars - object of required front matter variables
+ */
+const prependYAML = (contents, vars) => {
+    return contents
+        .replace(/^/, toYAML(vars) + '\n\n')
+        .replace(/[\r\n]{3,}/g, '\n\n');
+};
+exports.prependYAML = prependYAML;
+/**
+ * Returns the page title as rendered in the document h1(# title)
+ * @param page
+ */
+const getPageTitle = (page) => {
+    return reflection_title_1.reflectionTitle.call(page, false);
+};
+exports.getPageTitle = getPageTitle;
+/**
+ * Converts YAML object to a YAML string
+ * @param vars
+ */
+const toYAML = (vars) => {
+    const yaml = `---
+${Object.entries(vars)
+        .map(([key, value]) => `${key}: ${typeof value === 'string' ? `"${escapeString(value)}"` : value}`)
+        .join('\n')}
+---`;
+    return yaml;
+};
+// prettier-ignore
+const escapeString = (str) => str.replace(/([^\\])'/g, '$1\\\'');
+let FrontMatterComponent = class FrontMatterComponent extends components_2.RendererComponent {
+    constructor() {
+        super(...arguments);
+        this.globalsFile = 'modules.md';
+    }
+    initialize() {
+        super.initialize();
+        this.listenTo(this.application.renderer, {
+            [events_1.PageEvent.END]: this.onPageEnd,
+        });
+    }
+    onPageEnd(page) {
+        if (page.contents) {
+            page.contents = exports.prependYAML(page.contents, this.getYamlItems(page));
+        }
+    }
+    getYamlItems(page) {
+        const pageTitle = this.getTitle(page);
+        const sidebarLabel = this.getSidebarLabel(page);
+        let items = {
+            title: pageTitle,
+        };
+        if (sidebarLabel && sidebarLabel !== pageTitle) {
+            items = { ...items, sidebar_label: sidebarLabel };
+        }
+        return {
+            ...items,
+            custom_edit_url: null,
+            hide_title: true,
+        };
+    }
+    getSidebarLabel(page) {
+        if (!this.sidebar) {
+            return null;
+        }
+        if (page.url === this.entryDocument) {
+            return page.url === page.project.url
+                ? this.sidebar.indexLabel
+                : this.sidebar.readmeLabel;
+        }
+        if (page.url === this.globalsFile) {
+            return this.sidebar.indexLabel;
+        }
+        return this.sidebar.fullNames ? page.model.getFullName() : page.model.name;
+    }
+    getId(page) {
+        return path.basename(page.url, path.extname(page.url));
+    }
+    getTitle(page) {
+        const readmeTitle = this.readmeTitle || page.project.name;
+        if (page.url === this.entryDocument && page.url !== page.project.url) {
+            return readmeTitle;
+        }
+        return exports.getPageTitle(page);
+    }
+};
+__decorate([
+    typedoc_1.BindOption('out')
+], FrontMatterComponent.prototype, "out", void 0);
+__decorate([
+    typedoc_1.BindOption('sidebar')
+], FrontMatterComponent.prototype, "sidebar", void 0);
+__decorate([
+    typedoc_1.BindOption('globalsTitle')
+], FrontMatterComponent.prototype, "globalsTitle", void 0);
+__decorate([
+    typedoc_1.BindOption('readmeTitle')
+], FrontMatterComponent.prototype, "readmeTitle", void 0);
+__decorate([
+    typedoc_1.BindOption('entryDocument')
+], FrontMatterComponent.prototype, "entryDocument", void 0);
+FrontMatterComponent = __decorate([
+    components_1.Component({ name: 'front-matter' })
+], FrontMatterComponent);
+exports.FrontMatterComponent = FrontMatterComponent;

src/index.d.ts

@@ -0,0 +1 @@
+export { default } from './plugin';

src/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return plugin_1.default; } });

src/options.d.ts

@@ -0,0 +1,12 @@
+import { Application } from 'typedoc';
+import { PluginOptions } from './types';
+/**
+ * Merge default with user options
+ * @param opts
+ */
+export declare const getOptions: (siteDir: string, opts: Partial<PluginOptions>) => PluginOptions;
+/**
+ * Add docusaurus options to converter
+ * @param app
+ */
+export declare const addOptions: (app: Application) => void;

src/options.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addOptions = exports.getOptions = void 0;
+const path = require("path");
+const typedoc_1 = require("typedoc");
+/**
+ * Default plugin options
+ */
+const DEFAULT_PLUGIN_OPTIONS = {
+    id: 'default',
+    docsRoot: 'docs',
+    out: 'api',
+    entryDocument: 'index.md',
+    hideInPageTOC: true,
+    hideBreadcrumbs: true,
+    sidebar: {
+        fullNames: false,
+        sidebarFile: 'typedoc-sidebar.js',
+        indexLabel: 'Table of contents',
+        readmeLabel: 'Readme',
+        sidebarPath: '',
+    },
+    plugin: ['none'],
+    outputDirectory: '',
+    siteDir: '',
+    watch: false,
+};
+/**
+ * Merge default with user options
+ * @param opts
+ */
+const getOptions = (siteDir, opts) => {
+    // base options
+    let options = {
+        ...DEFAULT_PLUGIN_OPTIONS,
+        ...opts,
+    };
+    // sidebar
+    if (opts.sidebar === null) {
+        options = { ...options, sidebar: null };
+    }
+    else {
+        const sidebar = {
+            ...DEFAULT_PLUGIN_OPTIONS.sidebar,
+            ...opts.sidebar,
+        };
+        options = {
+            ...options,
+            sidebar: {
+                ...sidebar,
+                sidebarPath: path.resolve(siteDir, sidebar.sidebarFile),
+            },
+        };
+    }
+    // additional
+    options = {
+        ...options,
+        siteDir,
+        outputDirectory: path.resolve(siteDir, options.docsRoot, options.out),
+    };
+    return options;
+};
+exports.getOptions = getOptions;
+/**
+ * Add docusaurus options to converter
+ * @param app
+ */
+const addOptions = (app) => {
+    // configure deault typedoc options
+    app.options.addReader(new typedoc_1.TypeDocReader());
+    app.options.addReader(new typedoc_1.TSConfigReader());
+    // expose plugin options to typedoc so we can access if required
+    app.options.addDeclaration({
+        name: 'id',
+    });
+    app.options.addDeclaration({
+        name: 'docsRoot',
+    });
+    app.options.addDeclaration({
+        name: 'siteDir',
+    });
+    app.options.addDeclaration({
+        name: 'outputDirectory',
+    });
+    app.options.addDeclaration({
+        name: 'globalsTitle',
+    });
+    app.options.addDeclaration({
+        name: 'readmeTitle',
+    });
+    app.options.addDeclaration({
+        name: 'sidebar',
+        type: typedoc_1.ParameterType.Mixed,
+    });
+};
+exports.addOptions = addOptions;

src/plugin.d.ts

@@ -0,0 +1,2 @@
+import { PluginOptions } from './types';
+export default function generate(siteDir: string, opts: Partial<PluginOptions>): Promise<void>;

src/plugin.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const typedoc_1 = require("typedoc");
+const MarkdownPlugin = require("typedoc-plugin-markdown");
+const front_matter_1 = require("./front-matter");
+const options_1 = require("./options");
+const render_1 = require("./render");
+const sidebar_1 = require("./sidebar");
+async function generate(siteDir, opts) {
+    // we need to generate an empty sidebar up-front so it can be resolved from sidebars.js
+    const options = options_1.getOptions(siteDir, opts);
+    // if (options.sidebar) {
+    //   writeSidebar(options.sidebar, 'module.exports=[];');
+    // }
+    // initialize and build app
+    const app = new typedoc_1.Application();
+    // load the markdown plugin
+    MarkdownPlugin(app);
+    // customise render
+    app.renderer.render = render_1.render;
+    // add plugin options
+    options_1.addOptions(app);
+    // bootstrap typedoc app
+    app.bootstrap(options);
+    // add frontmatter component to typedoc renderer
+    app.renderer.addComponent('fm', new front_matter_1.FrontMatterComponent(app.renderer));
+    // add sidebar component to typedoc renderer
+    app.renderer.addComponent('sidebar', new sidebar_1.SidebarComponent(app.renderer));
+    // return the generated reflections
+    const project = app.convert();
+    // if project is undefined typedoc has a problem - error logging will be supplied by typedoc.
+    if (!project) {
+        return;
+    }
+    // generate or watch app
+    return app.generateDocs(project, options.outputDirectory);
+}
+exports.default = generate;

src/render.d.ts

@@ -0,0 +1,2 @@
+import { ProjectReflection } from 'typedoc';
+export declare function render(project: ProjectReflection, outputDirectory: string): Promise<void>;

src/render.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.render = void 0;
+const events_1 = require("typedoc/dist/lib/output/events");
+const ts = require("typescript");
+async function render(project, outputDirectory) {
+    var _a;
+    if (!this.prepareTheme() || !this.prepareOutputDirectory(outputDirectory)) {
+        return;
+    }
+    const output = new events_1.RendererEvent(events_1.RendererEvent.BEGIN, outputDirectory, project);
+    output.settings = this.application.options.getRawValues();
+    output.urls = this.theme.getUrls(project);
+    this.trigger(output);
+    if (!output.isDefaultPrevented) {
+        (_a = output.urls) === null || _a === void 0 ? void 0 : _a.forEach((mapping, i) => {
+            var _a;
+            this.renderDocument(output.createPageEvent(mapping));
+            ts.sys.write(`\rGenerated ${i + 1} of ${(_a = output.urls) === null || _a === void 0 ? void 0 : _a.length} TypeDoc docs`);
+        });
+        ts.sys.write(`\n`);
+        this.trigger(events_1.RendererEvent.END, output);
+    }
+}
+exports.render = render;

src/sidebar.d.ts

@@ -0,0 +1,26 @@
+import { RendererComponent } from 'typedoc/dist/lib/output/components';
+import { RendererEvent } from 'typedoc/dist/lib/output/events';
+import { SidebarItem, SidebarOptions } from './types';
+export declare class SidebarComponent extends RendererComponent {
+    sidebar: SidebarOptions;
+    siteDir: string;
+    out: string;
+    initialize(): void;
+    onRendererBegin(renderer: RendererEvent): Promise<void>;
+    /**
+     * returns a sidebar category node
+     */
+    getSidebarCategory(title: string, items: SidebarItem[]): {
+        type: string;
+        label: string;
+        items: SidebarItem[];
+    };
+    /**
+     * returns the url key for relevant doc
+     */
+    getUrlKey(out: string, url: string): string;
+}
+/**
+ * Write content to sidebar file
+ */
+export declare const writeSidebar: (sidebar: SidebarOptions, content: string) => void;

src/sidebar.js

@@ -0,0 +1,99 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSidebar = exports.SidebarComponent = void 0;
+const fs = require("fs");
+const path = require("path");
+const typedoc_1 = require("typedoc");
+const components_1 = require("typedoc/dist/lib/converter/components");
+const components_2 = require("typedoc/dist/lib/output/components");
+const events_1 = require("typedoc/dist/lib/output/events");
+const promises_1 = require("fs/promises");
+let SidebarComponent = class SidebarComponent extends components_2.RendererComponent {
+    initialize() {
+        this.listenTo(this.application.renderer, {
+            [events_1.RendererEvent.BEGIN]: this.onRendererBegin,
+        });
+    }
+    async onRendererBegin(renderer) {
+        var _a;
+        const navigation = (_a = this.application.renderer.theme) === null || _a === void 0 ? void 0 : _a.getNavigation(renderer.project);
+        const out = this.out.match(/(?:.*)en\/(.*)/)[1];
+        // map the navigation object to a Docuaurus sidebar format
+        const sidebarItems = (navigation === null || navigation === void 0 ? void 0 : navigation.children) ? navigation.children.map((navigationItem) => {
+            if (navigationItem.isLabel) {
+                const sidebarCategoryItems = navigationItem.children
+                    ? navigationItem.children.map((navItem) => {
+                        const url = this.getUrlKey(out, navItem.url);
+                        if (navItem.children && navItem.children.length > 0) {
+                            const sidebarCategoryChildren = navItem.children.map((childGroup) => this.getSidebarCategory(childGroup.title, childGroup.children
+                                ? childGroup.children.map((childItem) => this.getUrlKey(out, childItem.url))
+                                : []));
+                            return this.getSidebarCategory(navItem.title, [
+                                url,
+                                ...sidebarCategoryChildren,
+                            ]);
+                        }
+                        return url;
+                    })
+                    : [];
+                return this.getSidebarCategory(navigationItem.title, sidebarCategoryItems);
+            }
+            return this.getUrlKey(out, navigationItem.url);
+        })
+            : [];
+        const sidebarPath = this.sidebar.sidebarPath;
+        const sidebarContent = JSON.parse(await promises_1.readFile(sidebarPath, "utf-8"));
+        const index = sidebarContent.docs[3].items
+            .map((row, index) => (row.label && row.label === "JavaScript" ? index : 0))
+            .reduce((accumulator, value) => accumulator + value);
+        sidebarContent.docs[3].items[index].items = sidebarItems; // Specify where to put the items
+        promises_1.writeFile(sidebarPath, JSON.stringify(sidebarContent, null, 2));
+        this.application.logger.success(`TypeDoc sidebar written to ${sidebarPath}`);
+    }
+    /**
+     * returns a sidebar category node
+     */
+    getSidebarCategory(title, items) {
+        return {
+            type: 'category',
+            label: title,
+            items,
+        };
+    }
+    /**
+     * returns the url key for relevant doc
+     */
+    getUrlKey(out, url) {
+        const urlKey = url.replace('.md', '');
+        return out ? out + '/' + urlKey : urlKey;
+    }
+};
+__decorate([
+    typedoc_1.BindOption('sidebar')
+], SidebarComponent.prototype, "sidebar", void 0);
+__decorate([
+    typedoc_1.BindOption('siteDir')
+], SidebarComponent.prototype, "siteDir", void 0);
+__decorate([
+    typedoc_1.BindOption('out')
+], SidebarComponent.prototype, "out", void 0);
+SidebarComponent = __decorate([
+    components_1.Component({ name: 'sidebar' })
+], SidebarComponent);
+exports.SidebarComponent = SidebarComponent;
+/**
+ * Write content to sidebar file
+ */
+const writeSidebar = (sidebar, content) => {
+    if (!fs.existsSync(path.dirname(sidebar.sidebarPath))) {
+        fs.mkdirSync(path.dirname(sidebar.sidebarPath));
+    }
+    fs.writeFileSync(sidebar.sidebarPath, content);
+};
+exports.writeSidebar = writeSidebar;

src/types.d.ts

@@ -0,0 +1,41 @@
+export interface PluginOptions {
+    id: string;
+    docsRoot: string;
+    out: string;
+    sidebar: SidebarOptions | null;
+    readmeTitle?: string;
+    globalsTitle?: string;
+    plugin: string[];
+    readme?: string;
+    disableOutputCheck?: boolean;
+    entryPoints?: string[];
+    entryDocument: string;
+    hideInPageTOC: boolean;
+    hideBreadcrumbs: boolean;
+    siteDir: string;
+    outputDirectory: string;
+    watch: boolean;
+}
+export interface FrontMatter {
+    id?: string;
+    title: string;
+    slug?: string;
+    sidebar_label?: string;
+    hide_title?: boolean;
+}
+export interface SidebarOptions {
+    fullNames?: boolean;
+    sidebarFile: string;
+    sidebarPath: string;
+    indexLabel?: string;
+    readmeLabel?: string;
+}
+export interface Sidebar {
+    [sidebarId: string]: SidebarItem[];
+}
+export interface SidebarCategory {
+    type: string;
+    label: string;
+    items: SidebarItem[];
+}
+export declare type SidebarItem = SidebarCategory | string;

src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

src/watch.d.ts

@@ -0,0 +1,6 @@
+import { Application } from 'typedoc';
+import { PluginOptions } from './types';
+/**
+ * Calls TypeDoc's `convertAndWatch` and force trigger sidebars refresh.
+ */
+export declare const convertAndWatch: (app: Application, options: PluginOptions) => void;

src/watch.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertAndWatch = void 0;
+const fs = require("fs");
+const path = require("path");
+/**
+ * Calls TypeDoc's `convertAndWatch` and force trigger sidebars refresh.
+ */
+const convertAndWatch = (app, options) => {
+    const sidebarsJsPath = path.resolve(options.siteDir, 'sidebars.js');
+    app.convertAndWatch(async (project) => {
+        if (options.sidebar) {
+            // remove typedoc sidebar from require cache
+            delete require.cache[options.sidebar.sidebarPath];
+            // force trigger a sidebars.js refresh
+            const sidebarJsContent = fs.readFileSync(sidebarsJsPath);
+            fs.writeFileSync(sidebarsJsPath, sidebarJsContent);
+        }
+        await app.generateDocs(project, options.outputDirectory);
+    });
+};
+exports.convertAndWatch = convertAndWatch;

yarn.lock

@@ -2,11 +2,21 @@
 # yarn lockfile v1
 
 
+"@actions/core@^1.2.6":
+  version "1.2.6"
+  resolved "https://registry.yarnpkg.com/@actions/core/-/core-1.2.6.tgz#a78d49f41a4def18e88ce47c2cac615d5694bf09"
+  integrity sha512-ZQYitnqiyBc3D+k7LsgSBmMDVkOVidaagDG7j3fOym77jNunWRuYx7VSHa9GNfFZh+zh61xsCjRj4JxMZlDqTA==
+
 "@types/node@^14.14.35":
   version "14.14.35"
   resolved "https://registry.yarnpkg.com/@types/node/-/node-14.14.35.tgz#42c953a4e2b18ab931f72477e7012172f4ffa313"
   integrity sha512-Lt+wj8NVPx0zUmUwumiVXapmaLUcAk3yPuHCFVXras9k5VT9TdhJqKqGVUQCD60OTMCl0qxJ57OiTL0Mic3Iag==
 
+"@zeit/ncc@^0.22.3":
+  version "0.22.3"
+  resolved "https://registry.yarnpkg.com/@zeit/ncc/-/ncc-0.22.3.tgz#fca6b86b4454ce7a7e1e7e755165ec06457f16cd"
+  integrity sha512-jnCLpLXWuw/PAiJiVbLjA8WBC0IJQbFeUwF4I9M+23MvIxTxk5pD4Q8byQBSPmHQjz5aBoA7AKAElQxMpjrCLQ==
+
 at-least-node@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/at-least-node/-/at-least-node-1.0.0.tgz#602cd4b46e844ad4effc92a8011a3c46e0238dc2"