@forsakringskassan/docs-generator 2.12.0 → 2.14.0

package/README.md

@@ -11,10 +11,17 @@ npm install --save-dev --save-exact @forsakringskassan/docs-generator
 You can start a development server with watch for incremental builds using `.serve()`.
 
 ```ts
+import {
+    Generator,
+    livereloadProcessor,
+} from "@forsakringskassan/docs-generator";
+
 const docs = new Generator({
-    /* ... */
+    site: {
+        name: "My Awesome Site",
+    },
+    setupPath: "docs/src/setup.ts",
     processors: [livereloadProcessor({ enabled: true })],
-    /* ... */
 });
 
 docs.build([
@@ -29,8 +36,17 @@ docs.serve();
 Vendor alias is optional, it lets you substitute one package for another when bundling. The example below substitutes the package `vue` with the package `vue/dist/esm.bundle.js`. When an alias is given the package can be imported using the given alias as well as the original package name. For instance, when using the following configuration "vue" can be imported and resolved as "vue/dist/esm.bundle.js".
 
 ```ts
+import {
+    Generator,
+    livereloadProcessor,
+} from "@forsakringskassan/docs-generator";
+
 const docs = new Generator({
-    /* ... */
+    site: {
+        name: "My Awesome Site",
+    },
+    setupPath: "docs/src/setup.ts",
+
     vendor: [
         {
             package: "vue",
@@ -39,7 +55,6 @@ const docs = new Generator({
             alias: "vue/dist/esm.bundle.js",
         },
     ],
-    /* ... */
 });
 ```
 
@@ -55,7 +70,7 @@ npm install --save-dev --save-exact @vue/component-compiler
 
 Create the `setup` callback in `docs/src/setup.ts`:
 
-```ts
+```ts nocompile
 import Vue from "vue";
 import { type SetupOptions } from "@forsakringskassan/docs-generator";
 
@@ -73,7 +88,7 @@ export function setup(options: SetupOptions): void {
 
 Create the `setup` callback in `docs/src/setup.ts`:
 
-```ts
+```ts nocompile
 import { createApp } from "vue";
 import { type SetupOptions } from "@forsakringskassan/docs-generator";
 
@@ -102,8 +117,13 @@ Three CSS files are provided:
 Style can be compiled with `compileStyle(name, src, [options])`:
 
 ```ts
+import { Generator } from "@forsakringskassan/docs-generator";
+
 const docs = new Generator({
-    /* ... */
+    site: {
+        name: "My Awesome Site",
+    },
+    setupPath: "docs/src/setup.ts",
 });
 
 docs.compileStyle("docs", "./docs/src/style.scss", {
@@ -274,7 +294,7 @@ Defaults to `@fkui/icon-lib-default`.
 Makes it possible to dynamically load icons and get access to icon metadata.
 The library must have been built using `@fkui/icon-lib-builder`.
 
-```js
+```js nocompile
 const icons = await import(process.env.DOCS_ICON_LIB);
 
 for (const entry of Object.values(icons)) {

package/dist/compile-example.js

@@ -3,10 +3,10 @@
 var path$1 = require('node:path');
 var esbuild = require('esbuild');
 var vue = require('vue');
-var vue3 = require('./vue3-rkJOanAd.js');
+var vue3 = require('./vue3-BqgRpcI0.js');
 var path = require('node:path/posix');
 require('@vue/compiler-sfc');
-require('./vendor-CJBsNZrh.js');
+require('./vendor-Bb38Rlio.js');
 require('node:url');
 require('fs');
 require('node:fs');
@@ -14,6 +14,7 @@ require('node:fs/promises');
 require('node:events');
 require('node:stream');
 require('node:string_decoder');
+require('typescript');
 require('constants');
 require('stream');
 require('util');
@@ -25,7 +26,6 @@ require('node:process');
 require('node:util');
 require('node:child_process');
 require('node:stream/promises');
-require('typescript');
 require('fs/promises');
 require('os');
 require('http');

package/dist/{create-markdown-renderer-D5z4jt-T.js → create-markdown-renderer-DVss8WXD.js}

@@ -1,11 +1,14 @@
 'use strict';
 
-var vendor = require('./vendor-CJBsNZrh.js');
+var vendor = require('./vendor-Bb38Rlio.js');
 var path = require('node:path/posix');
 var path$1 = require('node:path');
 require('crypto');
 var crypto = require('node:crypto');
 require('node:child_process');
+var fs = require('node:fs');
+var vue = require('vue');
+var vue3 = require('./vue3-BqgRpcI0.js');
 
 function findDocument(haystack, needle) {
   const match = haystack.find((it) => {
@@ -65,6 +68,236 @@ function getOutputFilePath(outputFolder, fileInfo) {
   return normalizePath(outputFolder, path, outputName);
 }
 
+function parseImport(raw) {
+  const comments = [];
+  const stripped = raw.replace(/<!--.*?-->/gms, (match) => {
+    comments.push(match);
+    return "";
+  });
+  const filename = stripped.trim();
+  const extension = path$1.parse(filename).ext.slice(1);
+  return {
+    filename,
+    extension,
+    comments
+  };
+}
+
+function getExampleImport(searchDirs, filename) {
+  const pattern = searchDirs.map((dir) => `${dir}/**/${filename}`);
+  const matches = vendor.globSync(pattern);
+  if (matches.length === 0) {
+    const message = `No files matched import "${filename}"`;
+    throw new Error(message);
+  } else if (matches.length > 1) {
+    const message = `Multiple files matched import "${filename}"`;
+    throw new Error(message);
+  } else {
+    return normalizePath(matches[0]);
+  }
+}
+
+function getExampleName(filename) {
+  return path$1.parse(filename).name;
+}
+
+function removeLinesInline(lines, { begin, end }) {
+  for (let i = begin; i <= end; i++) {
+    lines[i] = "";
+  }
+  if (lines[begin - 1] === "\n") {
+    lines[begin - 1] = "";
+    begin--;
+  }
+  if (lines[end + 1] === "\n") {
+    lines[end + 1] = "";
+  }
+  if (end === lines.length - 1 && begin > 0) {
+    lines[begin - 1] = lines[begin - 1].slice(0, -1);
+  }
+}
+function cutSnippets(code) {
+  const lines = code.split(/\n/).map((it, index, lines2) => index < lines2.length - 1 ? `${it}
+` : it);
+  const directive = /\/\* +--- +cut (above|below|begin|end) +--- +\*\//;
+  let buffer = -1;
+  lines.forEach((line, index) => {
+    const match = line.match(directive);
+    const [, instruction] = match ?? ["", null];
+    if (!instruction) {
+      return;
+    }
+    switch (instruction) {
+      /* --- cut above --- */
+      case "above":
+        removeLinesInline(lines, {
+          begin: 0,
+          end: index
+        });
+        break;
+      /* --- cut below --- */
+      case "below":
+        removeLinesInline(lines, {
+          begin: index,
+          end: lines.length - 1
+        });
+        break;
+      /* --- cut begin --- */
+      case "begin":
+        if (buffer === -1) {
+          buffer = index;
+        }
+        break;
+      /* --- cut end --- */
+      case "end":
+        removeLinesInline(lines, {
+          begin: Math.max(buffer, 0),
+          end: index
+        });
+        buffer = -1;
+        break;
+    }
+  });
+  if (buffer >= 0) {
+    removeLinesInline(lines, {
+      begin: buffer,
+      end: lines.length - 1
+    });
+  }
+  return lines.join("");
+}
+function stripEslintComments(code) {
+  const matchLine = /^[ \t]*(\/\* eslint-disable[^*]*\*\/|\/\/ eslint-disable.*)\n/gm;
+  const matchEmbedded = /[ \t]*(\/\* eslint-disable[^*]*\*\/|\/\/ eslint-disable.*)/g;
+  return code.replace(matchLine, "").replace(matchEmbedded, "");
+}
+function maybeDedent(value) {
+  if (/^\s*$/.test(value)) {
+    return value;
+  }
+  if (/^\s/.test(value)) {
+    return vendor.dedent(value);
+  } else {
+    return value;
+  }
+}
+const transformations = {
+  javascript: [cutSnippets, stripEslintComments, maybeDedent],
+  typescript: [cutSnippets, stripEslintComments, maybeDedent]
+};
+function transformCode(code, lang) {
+  const fns = transformations[lang] ?? [];
+  for (const fn of fns) {
+    code = fn(code);
+  }
+  return code;
+}
+
+const vueMajor = parseInt(vue.version.split(".", 2)[0], 10);
+function vueGenerator() {
+  switch (vueMajor) {
+    case 2:
+      throw new Error(
+        "Vue 2 is no longer supported, upgrade to Vue 3 or downgrade docs-generator"
+      );
+    case 3:
+      return vue3.generateCode;
+  }
+}
+function generateExample(options) {
+  const { language } = options;
+  if (language === "import") {
+    const parsed = parseImport(options.source);
+    const filename = getExampleImport(
+      options.exampleFolders,
+      parsed.filename
+    );
+    const language2 = parsed.extension;
+    const comments = parsed.comments;
+    const content = fs.readFileSync(filename, "utf-8");
+    const source = transformCode(content, language2);
+    const example = generateExample({
+      ...options,
+      source,
+      language: language2,
+      filename
+    });
+    return { ...example, comments };
+  }
+  switch (language) {
+    case "vue":
+      return generateVueExample(options);
+    case "html":
+      return generateStaticExample(options);
+    default:
+      return generateStaticExample(options);
+  }
+}
+function generateVueExample(options) {
+  const { filename, source, parent, setupPath, tags } = options;
+  const fn = vueGenerator();
+  const slug = getExampleName(filename);
+  const fingerprint = getFingerprint(source);
+  const { markup, sourcecode, output } = fn({
+    filename,
+    slug,
+    fingerprint,
+    code: source,
+    setupPath
+  });
+  return {
+    source,
+    language: options.language,
+    comments: [],
+    tags,
+    markup,
+    output,
+    runtime: true,
+    task: {
+      outputFile: output,
+      sourcecode,
+      sourceFile: filename,
+      parent
+    }
+  };
+}
+function generateStaticExample(options) {
+  const { filename, source, language, tags } = options;
+  const slug = getExampleName(filename);
+  const fingerprint = getFingerprint(source);
+  const asset = `${slug}-${fingerprint}.${language}`;
+  const runtimeLanguages = ["html"];
+  const runtime = runtimeLanguages.includes(language);
+  return {
+    source,
+    language: options.language,
+    comments: [],
+    tags,
+    markup: source,
+    output: runtime ? asset : null,
+    runtime,
+    task: null
+  };
+}
+
+function normalizeLanguage(lang) {
+  switch (lang) {
+    case "ts":
+      return "typescript";
+    case "js":
+      return "javascript";
+    default:
+      return lang;
+  }
+}
+function parseInfostring(infostring) {
+  const [rawLanguage, ...rawTags] = infostring.trim().split(/\s+/);
+  return {
+    language: normalizeLanguage(rawLanguage),
+    tags: rawTags
+  };
+}
+
 class SoftError extends Error {
   code;
   details;
@@ -274,16 +507,17 @@ function codePreview(options) {
   };
   function fence(_md, tokens, idx, _options, env) {
     const { fileInfo } = env;
-    const { content: source, info, map } = tokens[idx];
-    const [language, ...rawTags] = info.split(/\s+/);
+    const { content: rawSource, info, map } = tokens[idx];
+    const { language, tags: rawTags } = parseInfostring(info);
     if (language === "mermaid") {
       return (
         /* HTML */
         `
-                <pre class="mermaid">${htmlencode(source)}</pre>
+                <pre class="mermaid">${htmlencode(rawSource)}</pre>
             `
       );
     }
+    const source = transformCode(rawSource, language);
     const example = generateExample({
       source,
       language,
@@ -774,7 +1008,9 @@ function createMarkdownRenderer(options) {
 
 exports.SoftError = SoftError;
 exports.createMarkdownRenderer = createMarkdownRenderer;
+exports.generateExample = generateExample;
 exports.generateId = generateId;
 exports.getFingerprint = getFingerprint;
 exports.getOutputFilePath = getOutputFilePath;
 exports.normalizePath = normalizePath;
+exports.parseInfostring = parseInfostring;

package/dist/index.d.ts

@@ -112,6 +112,23 @@ export declare interface DocumentOutlineEntry {
     subheadings: DocumentOutline;
 }
 
+/**
+ * Options for `extractExamplesProcessor`.
+ *
+ * @public
+ */
+export declare interface ExtractExamplesOptions extends ProcessorOptions {
+    outputFolder: string;
+    languages?: string[];
+}
+
+/**
+ * Processor to extract and write examples to separate files.
+ *
+ * @public
+ */
+export declare function extractExamplesProcessor(options: ExtractExamplesOptions): Processor;
+
 /**
  * @public
  */
@@ -199,10 +216,12 @@ export { Generator_2 as Generator }
 export declare interface GeneratorOptions {
     /** Site options */
     site: GeneratorSiteOptions;
-    outputFolder: string;
-    cacheFolder: string;
-    /** List of folders to search when locating examples (searched recursively) */
-    exampleFolders: string[];
+    /** Output folder. Default: `public` */
+    outputFolder?: string;
+    /** Where cached content is stored. Default: `temp/docs` */
+    cacheFolder?: string;
+    /** List of folders to search when locating examples (searched recursively). Default: `[]` */
+    exampleFolders?: string[];
     /** List of folders to search when locating templates. */
     templateFolders?: string[];
     /** List of extra processors to run */
@@ -216,11 +235,11 @@ export declare interface GeneratorOptions {
     /**
      * Options for markdown renderer.
      */
-    markdown: {
+    markdown?: {
         /**
          * Options for markdown messagebox container.
          */
-        messagebox: {
+        messagebox?: {
             /**
              * Default titles for messageboxes.
              *
@@ -345,7 +364,7 @@ export declare interface MOTDOptions {
  *
  * @public
  */
-export declare function motdProcessor(options: MOTDOptions): Processor;
+export declare function motdProcessor(options?: MOTDOptions): Processor;
 
 /**
  * Read a JSON file with arbitrary navigation entries.