Add markdown/glimdown rendering, TypeDoc, etc

.attw.json

@@ -1,3 +1,4 @@
 {
-  "ignoreRules": ["no-resolution", "cjs-resolves-to-esm"]
+  "ignoreRules": ["no-resolution", "cjs-resolves-to-esm"],
+  "excludeEntrypoints": ["webpack", "vite"]
 }

.github/workflows/ci.yml

@@ -18,6 +18,20 @@ env:
   TURBO_API: http://127.0.0.1:9080
   TURBO_TOKEN: this-is-not-a-secret
   TURBO_TEAM: myself
+  # We have a real case where the verification is incorrect,
+  # webpack appears to only ship one copy of ember-source
+  #
+  # We can deduce this without debugging too hard, because:
+  # - we know that ember-source includes `@glimmer/validator`
+  #   (bundled, not as a dependency)
+  # - we know that `@glimmer/validator` has conniptions if it
+  #   is included twice in the same app - an error is thrown.
+  #
+  # And right now, there is no error about `@glimmer/validator`
+  # being included twice.
+  #
+  # See: https://github.com/embroider-build/embroider/issues/1789
+  I_HAVE_BAD_PEER_DEPS_AND_WANT_A_BROKEN_BUILD: true
 
 ##############################################################
 
@@ -47,7 +61,7 @@ jobs:
       - uses: wyvox/action@v1
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-      - run: pnpm lint
+      - run: pnpm turbo _:lint
 
   ##############################################################
 

docs-app/.template-lintrc.js

@@ -2,4 +2,8 @@
 
 module.exports = {
   extends: 'recommended',
+  rules: {
+    'no-forbidden-elements': 'off',
+    'no-inline-styles': 'off',
+  },
 };

docs-app/app/router.js

@@ -1,10 +1,15 @@
 import EmberRouter from '@ember/routing/router';
 
 import config from 'docs-app/config/environment';
+import { properLinks } from 'ember-primitives/proper-links';
+import { addRoutes } from 'kolay';
 
+@properLinks
 export default class Router extends EmberRouter {
   location = config.locationType;
   rootURL = config.rootURL;
 }
 
-Router.map(function () {});
+Router.map(function () {
+  addRoutes(this);
+});

docs-app/app/routes/application.ts

@@ -1,8 +1,24 @@
 import Route from '@ember/routing/route';
+import { service } from '@ember/service';
 
 export default class ApplicationRoute extends Route {
+  @service('kolay/docs') docs;
+
   async model() {
-    const request = await fetch('/docs/manifest.json');
+    // TODO?: Should setup also fetch the manifest?
+    //        then we just await setup here?
+    this.docs.setup({
+      // TODO: can be determined by createManifest plugin
+      //       (if it emits a virtual module)
+      manifest: '/docs/manifest.json',
+
+      resolve: {
+        'ember-primitives': await import('ember-primitives'),
+        kolay: await import('kolay'),
+      },
+    });
+
+    const request = await fetch(this.docs.manifestLocation);
     const json = await request.json();
 
     return { manifest: json };

docs-app/app/templates/application.gjs

@@ -1,17 +1,38 @@
-// NOTE: this is a virtual module and doesn't actually exist
-//       the build emits it
 import ENV from 'docs-app/config/environment';
 import { pageTitle } from 'ember-page-title';
 import Route from 'ember-route-template';
 
-import { Demo } from './demo/logs';
+const Nav = <template>
+  <ul>
+    {{#each @item.pages as |page|}}
+      {{#if page.path}}
+        <li>
+          <a href={{page.path}}>{{page.name}}</a>
+        </li>
+      {{else}}
+        <li>
+          {{page.name}}
+          <Nav @item={{page}} />
+        </li>
+      {{/if}}
+    {{/each}}
+  </ul>
+</template>;
 
 export default Route(
   <template>
     {{pageTitle ENV.APP.shortVersion}}
 
-    {{outlet}}
-    <Demo />
-    <pre><code>{{JSON.stringify @model.manifest null 3}}</code></pre>
+    <div class="application__layout">
+      <nav>
+        <Nav @item={{@model.manifest.tree}} />
+      </nav>
+      <main>
+        {{outlet}}
+      </main>
+    </div>
+    <style>
+      .application__layout { display: grid; grid-template-columns: max-content 1fr; gap: 1rem; }
+    </style>
   </template>
 );

docs-app/app/templates/page.gjs

@@ -0,0 +1,25 @@
+import { service } from 'ember-primitives/helpers';
+import Route from 'ember-route-template';
+import { highlight } from 'kolay';
+
+export default Route(
+  <template>
+    {{#let (service "kolay/docs") as |docs|}}
+      <div
+        data-prose
+        class="prose p-4"
+        {{(if docs.selected.prose (modifier highlight docs.selected.prose))}}
+      >
+        {{#if docs.selected.hasError}}
+          <div style="border: 1px solid red; padding: 1rem;">
+            {{docs.selected.error}}
+          </div>
+        {{/if}}
+
+        {{#if docs.selected.prose}}
+          <docs.selected.prose />
+        {{/if}}
+      </div>
+    {{/let}}
+  </template>
+);

docs-app/ember-cli-build.js

@@ -9,7 +9,7 @@ module.exports = async function (defaults) {
 
   const { Webpack } = require('@embroider/webpack');
 
-  const { createManifest } = await import('kolay/webpack');
+  const { createManifest, apiDocs } = await import('kolay/webpack');
 
   return require('@embroider/compat').compatBuild(app, Webpack, {
     staticAddonTestSupportTrees: true,
@@ -18,7 +18,7 @@ module.exports = async function (defaults) {
     staticModifiers: true,
     staticComponents: true,
     // https://github.com/emberjs/ember.js/issues/20640
-    // staticEmberSource: true,
+    staticEmberSource: false,
     skipBabel: [
       {
         package: 'qunit',
@@ -27,7 +27,12 @@ module.exports = async function (defaults) {
     packagerOptions: {
       webpackConfig: {
         devtool: 'source-map',
-        plugins: [createManifest({ src: 'public/docs', dest: 'docs' })],
+        plugins: [
+          createManifest({ src: 'public/docs' }),
+          apiDocs({ package: 'kolay' }),
+          apiDocs({ package: 'ember-primitives' }),
+          apiDocs({ package: 'ember-resources' }),
+        ],
       },
     },
   });

docs-app/package.json

@@ -26,7 +26,6 @@
     "test:ember": "ember test"
   },
   "devDependencies": {
-    "pnpm-sync-dependencies-meta-injected": "^0.0.10",
     "@babel/core": "^7.23.6",
     "@babel/eslint-parser": "^7.23.3",
     "@babel/plugin-proposal-decorators": "^7.23.6",
@@ -39,8 +38,12 @@
     "@embroider/webpack": "3.2.2-unstable.12a42ca",
     "@glimmer/component": "^1.1.2",
     "@glimmer/tracking": "^1.1.2",
+    "@glint/core": "^1.3.0",
+    "@glint/environment-ember-loose": "^1.3.0",
+    "@glint/environment-ember-template-imports": "^1.3.0",
     "@glint/template": "^1.3.0",
     "@nullvoxpopuli/eslint-configs": "^3.2.2",
+    "@tsconfig/ember": "^3.0.3",
     "broccoli-asset-rev": "^3.0.0",
     "concurrently": "^8.2.2",
     "ember-auto-import": "^2.7.0",
@@ -69,6 +72,7 @@
     "eslint-plugin-prettier": "^5.0.1",
     "eslint-plugin-qunit": "^8.1.1",
     "loader.js": "^4.7.0",
+    "pnpm-sync-dependencies-meta-injected": "^0.0.10",
     "prettier": "^3.1.1",
     "prettier-plugin-ember-template-tag": "^2.0.0",
     "qunit": "^2.20.0",
@@ -77,6 +81,7 @@
     "stylelint-config-standard": "^36.0.0",
     "stylelint-prettier": "^5.0.0",
     "tracked-built-ins": "^3.3.0",
+    "typescript": "^5.3.3",
     "webpack": "^5.89.0"
   },
   "engines": {
@@ -89,12 +94,20 @@
     "extends": "../package.json"
   },
   "dependencies": {
+    "@universal-ember/kolay-ui": "workspace:^",
+    "ember-async-data": "^1.0.3",
+    "ember-cached-decorator-polyfill": "^1.0.2",
+    "ember-repl": "3.0.0",
     "ember-route-template": "^1.0.3",
-    "kolay": "workspace:^"
+    "kolay": "workspace:^",
+    "reactiveweb": "^1.2.1"
   },
   "dependenciesMeta": {
     "kolay": {
       "injected": true
+    },
+    "@universal-ember/kolay-ui": {
+      "injected": true
     }
   }
 }

docs-app/public/docs/components/api-docs.md

@@ -0,0 +1,5 @@
+# `<APIDocs />`
+
+```hbs live
+<APIDocs @module="declarations/browser/re-exports" @name="APIDocs" @apiDocs="/docs/kolay.json" />
+```

docs-app/public/docs/components/comment-query.md

@@ -0,0 +1 @@
+# `<CommentQuery />`

docs-app/public/docs/components/component-signature.md

@@ -0,0 +1 @@
+# `<ComponentSignature />`

docs-app/app/templates/demo/logs.gjs → docs-app/public/docs/components/logs.md

@@ -1,9 +1,11 @@
-import { Form } from 'ember-primitives';
-import { Logs } from 'kolay';
+# `<Logs />`
+
+```gjs live no-shadow
+import { Form } from "ember-primitives";
+import { Logs } from "kolay";
 
 function addToLog(y) {
-  // eslint-disable-next-line no-console
-  console.log(y.logInput);
+  console.info(y.logInput);
 }
 
 export const Demo = <template>
@@ -16,3 +18,4 @@ export const Demo = <template>
 
   <Logs />
 </template>;
+```

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

@@ -0,0 +1 @@
+# `apiDocs(...)`

docs-app/public/docs/plugins/copy-file-to-public.md

@@ -0,0 +1 @@
+# `copyFileToPublic(...)`

docs-app/public/docs/plugins/copy-file.md

@@ -0,0 +1 @@
+# `copyFile(...)`

docs-app/public/docs/plugins/create-manifest.md

@@ -0,0 +1,9 @@
+# `createManifest(...)`
+
+```hbs live
+<APIDocs @module="declarations/plugins/vite" @name="createManifest" @apiDocs="/docs/kolay.json" />
+```
+
+```hbs live
+<APIDocs @module="src/plugins/types" @name="CreateManifestOptions" @apiDocs="/docs/kolay.json" />
+```

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

@@ -1,3 +1,12 @@
 # Build Plugins
 
-foo
+Kolay requires some build-time static analysis to function.
+
+[`createManifest(...)`](/plugins/create-manifest.md) is the only required plugin. This generates the navigation and information about how Kolay's runtime code will fetch the markdown documents deployed with the app's static assets.
+
+Additionally, you may want [`apiDocs(...)`](/plugins/api-docs.md) to render JSDoc information generated from your library's type declarations. Rendering these uses the [Signature Components]() or [`APIDocs`]() components.
+
+There are also a couple utility plugins that may or may not be useful as you build your documentation app.
+
+- [copyFile(...)](/plugins/copy-file.md)
+- [copyFileToPublic(...)](/plugins/copy-file-to-public.md)

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

@@ -0,0 +1,82 @@
+<h1 style="
+  font-size: 2rem; 
+  display: inline-block; 
+  margin-bottom: 0; 
+  padding-bottom: 0">kolay</h1> 
+<small><code>adjective</code></small>
+
+<ul style="margin: 0; padding-left: 1rem; padding-bottom: 0;">
+    <li>easy</li>
+    <li>simple</li>
+    <li>uncomplicated</li>
+</ul>
+
+<small style="
+  float: right; 
+  margin-top: -2rem; 
+  font-size: 0.5rem;">after initial setup</small>
+
+<hr>
+
+## Setup
+
+There are two areas of configuration needed: buildtime, and runtime.
+
+### Build: Embroider + Webpack
+
+import `kolay/webpack`
+
+```js
+const { createManifest, apiDocs } = await import("kolay/webpack");
+
+return require("@embroider/compat").compatBuild(app, Webpack, {
+  /* ... */
+  packagerOptions: {
+    webpackConfig: {
+      devtool: "source-map",
+      plugins: [createManifest({ src: "public/docs" }), apiDocs({ package: "kolay" })],
+    },
+  },
+});
+```
+
+You can create docs for multiple libraries by invoking these plugins more than once:
+
+```js
+devtool: 'source-map',
+plugins: [
+  createManifest({ src: 'public/docs', name: 'own-manifest.json' }),
+  apiDocs({ package: 'kolay' }),
+  createManifest({ src: '../../my-library', name: 'my-library-manifest.json' }),
+  apiDocs({ package: 'my-library' }),
+],
+```
+
+See related for
+
+- [createManifest(...)](/plugins/create-manifest.md)
+- [apiDocs(...)](/plugins/api-docs.md)
+- [All Build Plugins](/plugins/index.md)
+
+### Runtime: Routing
+
+If using `@ember/routing/router` or `@embroider/router`
+
+You'll want to also install `ember-primitives`, so that you can use the [`@properLinks`] decorator on the router, giveng you the ability to _just use anchor tags (`<a>`)_ (a requirement for in-browser linking in markdown).
+
+```js
+import { kolayRoutes } from "kolay";
+import { properLinks } from "ember-primitives/proper-links";
+
+@properLinks
+export default class Router extends EmberRouter {
+  location = config.locationType;
+  rootURL = config.rootURL;
+}
+
+Router.map(function () {
+  kolayRoutes(this);
+});
+```
+
+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.