Merge pull request #46 from universal-ember/updated-setup-docs-and-te…

…sting

More docs, testing, complete setup, etc

docs-app/app/routes/application.ts

@@ -27,10 +27,6 @@ export default class ApplicationRoute extends Route {
         import('shiki/langs/handlebars.mjs'),
         import('shiki/langs/jsonc.mjs'),
       ],
-      langAlias: {
-        gjs: 'glimmer-js',
-        gts: 'glimmer-ts',
-      },
       loadWasm: getWasm,
     });
 

docs-app/ember-cli-build.js

@@ -41,7 +41,7 @@ module.exports = async function (defaults) {
                 src: '../ui/docs',
               },
             ],
-            packages: ['kolay', 'ember-primitives', 'ember-resources'],
+            packages: ['kolay'],
           }),
         ],
       },

docs-app/public/docs/plugins/helpers.md

@@ -0,0 +1,20 @@
+# Helper utilities
+
+These utilities can be imported and used within your own projects, as they are already used within `kolay`.
+This should allow users to build their own specific set of outputs using the same underying tools that `kolay` uses.
+
+```hbs live no-shadow
+<APIDocs @module="declarations/plugins" @name="gitRef" @package="kolay" />
+```
+
+```hbs live no-shadow
+<APIDocs @module="declarations/plugins" @name="packageTypes" @package="kolay" />
+```
+
+```hbs live no-shadow
+<APIDocs @module="declarations/plugins" @name="virtualFile" @package="kolay" />
+```
+
+```hbs live no-shadow
+<APIDocs @module="declarations/plugins" @name="generateTypeDocJSON" @package="kolay" />
+```

docs-app/public/docs/usage/setup.md

@@ -102,3 +102,74 @@ Router.map(function () {
 ```
 
 In the spirit of dynamically compiled and discovered docs, this adds a `*wildcard` route that matches all paths and then tries to derive which file to load from there.
+
+### Runtime: Rendering and Highlighting
+
+Here is what this site does
+
+- setup shiki for highlighting
+  - installed as a rehype plugin
+  - custom set of initially loaded syntaxes, for best experience
+- mandatory setup (`apiDocs` and `manifest`)
+- additional `resolve` entries for code blocks to pull from
+
+```ts
+// app/routes/application.ts
+import Route from "@ember/routing/route";
+import { service } from "@ember/service";
+
+import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
+import { colorScheme, sync } from "ember-primitives/color-scheme";
+import { getHighlighterCore } from "shiki/core";
+import getWasm from "shiki/wasm";
+
+sync();
+
+import type { DocsService, Manifest } from "kolay";
+
+export default class ApplicationRoute extends Route {
+  @service("kolay/docs") declare docs: DocsService;
+
+  async model(): Promise<{ manifest: Manifest }> {
+    const highlighter = await getHighlighterCore({
+      themes: [import("shiki/themes/github-dark.mjs"), import("shiki/themes/github-light.mjs")],
+      langs: [
+        import("shiki/langs/javascript.mjs"),
+        import("shiki/langs/typescript.mjs"),
+        import("shiki/langs/bash.mjs"),
+        import("shiki/langs/css.mjs"),
+        import("shiki/langs/html.mjs"),
+        import("shiki/langs/glimmer-js.mjs"),
+        import("shiki/langs/glimmer-ts.mjs"),
+        import("shiki/langs/handlebars.mjs"),
+        import("shiki/langs/jsonc.mjs"),
+      ],
+      loadWasm: getWasm,
+    });
+
+    await this.docs.setup({
+      apiDocs: import("kolay/api-docs:virtual"),
+      manifest: import("kolay/manifest:virtual"),
+      resolve: {
+        "ember-primitives": import("ember-primitives"),
+        kolay: import("kolay"),
+      },
+      rehypePlugins: [
+        [
+          rehypeShikiFromHighlighter,
+          highlighter,
+          {
+            defaultColor: colorScheme.current === "dark" ? "dark" : "light",
+            themes: {
+              light: "github-light",
+              dark: "github-dark",
+            },
+          },
+        ],
+      ],
+    });
+
+    return { manifest: this.docs.manifest };
+  }
+}
+```

docs-app/public/docs/usage/testing.md

@@ -0,0 +1,24 @@
+# Testing
+
+Testing will require a setup phase so that only your tests that actually need the kolay behavior will cause the kolay behavior to be used.
+
+If using qunit,
+
+```js
+import { setupKolay } from "kolay/test-support";
+
+module("my test group", function (hooks) {
+  setupRenderingTest(hooks);
+  setupKolay(hooks, async () => ({
+    apiDocs: await import("kolay/api-docs:virtual"),
+    manifest: await import("kolay/manifest:virtual"),
+  }));
+
+  test("self", async function (assert) {
+    // ...
+  });
+});
+```
+
+In ember application tests, the `setup` method from the docs service
+will have already been called from the application route, so this isn't needed.

src/plugins/api-docs/typedoc.js

@@ -10,10 +10,17 @@ import { packageTypes } from '../helpers.js';
 const require = createRequire(import.meta.url);
 
 /**
+ * Generates APIDocs / TypeDoc from already built declarations. This is meant to use be very permissive and ignore errors so that likelihood of generating a TypeDoc json document increases.
+ * Over time, this'll probably need to be tweaked, and maybe one day will need an extension API, but for now the only option is specifying which `packageName` to try to generate types for.
+ *
+ * Package lookup occurs relative to the package at the current working directory, using `require.resolve`.
+ * So only packages declared as (dev)dependencies entries can be found.
+ *
  * @typedef {object} Options
  * @property {string} packageName
  *
  * @param {Options} options
+ * @return {Promise<unknown | undefined>} either the built JSON document, or undefined
  */
 export async function generateTypeDocJSON({ packageName }) {
   /**

src/plugins/git-ref.js

@@ -1,5 +1,27 @@
 import { execSync } from 'node:child_process';
 
+/**
+ * A build-time utulity, used for getting the short version of the git SHA.
+ *
+ * Could be used to hide somewhere in your app so that you know what specific version is deployed.
+ *
+ * In an ESM environment, you can import this module:
+ * ```js
+ * import { gitRef } from 'kolay/build';
+ *
+ * // in some config
+ * version: gitRef()
+ * ```
+ *
+ * In a CJS environment, you'd require this module:
+ * ```js
+ * const { gitRef } = require('kolay/build/legacy');
+ *
+ * // in some config
+ * version: gitRef()
+ * ```
+ *
+ */
 export function gitRef() {
   const scriptOutput = execSync('git rev-parse --short HEAD', {
     encoding: 'utf-8',

src/plugins/helpers.js

@@ -22,6 +22,8 @@ const require = createRequire(import.meta.url);
 export const INTERNAL_PREFIX = `\0`;
 
 /**
+ * Gather the `types` entries from `package.json#exports`
+ *
  * @param {string} packageName
  */
 export async function packageTypes(packageName) {
@@ -72,6 +74,8 @@ function extractExports(exports, kind) {
 }
 
 /**
+ * Create a virtual file in a rollup-based API by only specifying the desired import path and the content of the virtual file.
+ *
  * @typedef {object} VirtualFileOptions
  * @property {string} importPath
  * @property {string} content

src/plugins/index.js

@@ -1,3 +1,4 @@
+export { generateTypeDocJSON } from './api-docs/typedoc.js';
 export { combined as kolay } from './combined.js';
 export { gitRef } from './git-ref.js';
-export * as helpers from './helpers.js';
+export { packageTypes, virtualFile } from './helpers.js';