save point

gohypergiant · Dec 5, 2024 · c2f9245 · c2f9245
1 parent 9674cae
commit c2f9245
Show file tree

Hide file tree

Showing 10 changed files with 1,270 additions and 9 deletions.
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,2 @@
+# Accelint Standard Toolkit
+
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,3 @@
+* [Home](/)
+* [Constants](/constants.md)
+* [Geo](/geo.md)
diff --git a/docs/constants.md b/docs/constants.md
@@ -0,0 +1,22 @@
+# Constants
+
+## Coordinates
+
+Some content about why we chose to do things the way they are done.
+
+```playground
+{
+  "module": "packages/constants/src/coordinates/index.ts",
+  "render": true
+}
+```
+
+More detail about decisions or possible runway for development.
+
+## Identifiers
+
+```playground
+{
+  "module": "packages/constants/src/identifiers/index.ts"
+}
+```
diff --git a/docs/favicon.ico b/docs/favicon.ico
diff --git a/docs/geo.md b/docs/geo.md
@@ -0,0 +1,10 @@
+# Geo
+
+## Coordinate
+
+```playground
+{
+  "module": "packages/geo/src/coordinates/coordinate.ts",
+  "render": false
+}
+```
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,109 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+
+  <title>Documentation - Accelint Standard Toolkit</title>
+
+  <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible" />
+  <meta content="Description" name="description" />
+  <meta content="width=device-width, initial-scale=1.0, minimum-scale=1.0" name="viewport" />
+
+  <link href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" rel="stylesheet" />
+
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module">
+    import { parse } from 'https://cdn.jsdelivr.net/npm/[email protected]/+esm';
+    import { parse as marked } from 'https://cdn.jsdelivr.net/npm/[email protected]/+esm';
+
+    class Playground extends HTMLElement {
+      static #root = 'https://raw.githubusercontent.com/gohypergiant/standard-toolkit/refs/heads/main';
+
+      #config;
+
+      constructor() {
+        super();
+
+        this.#config = JSON.parse(this.innerText)
+
+        this.classList.add('code-playground')
+      }
+
+      connectedCallback() {
+        fetch(`${Playground.#root}/${this.#config.module}`)
+          .then((r) => r.text())
+          .then(this.#render.bind(this));
+      }
+
+      #render(body) {
+        let source = body;
+        const comments = parse(source)[0];
+
+        this.innerHTML = '';
+
+        if (comments) {
+          let content = comments.description ?? '';
+
+          const examples = comments.tags
+            .filter(({tag}) => tag === 'example')
+            .map(({ source }) => source.slice(1, -1).map(({tokens}) => tokens.description).join('\n'))
+            .join('\n');
+
+          if (examples) {
+            content += [
+              '',
+              '### Example',
+              '```typescript',
+              examples,
+              '```',
+            ].join('\n');
+          }
+
+          this.innerHTML = marked([
+              content,
+              '### Source',
+            ].join('\n'));
+        }
+
+
+        if (this.#config.render) {
+          this.innerHTML += '<figure style="border: 1px solid gainsboro; margin: 0; padding: 1em;">Demo rendering... [TBD]</figure>'
+        }
+
+        if (body.includes('Copyright 2024 Hypergiant Galactic Systems Inc. All rights reserved')) {
+          source = source.replace(/\/\*[\w\W]+?\*\/\W+/m, '')
+        }
+
+        this.innerHTML += `<pre style="margin: 0; max-height: 36em;"><code class="lang-typescript">${source}</code></pre>`
+
+        Array.from(this.querySelectorAll('code')).forEach((el) => {
+          Prism.highlightElement(el);
+        })
+      }
+    }
+
+    customElements.define('code-playground', Playground);
+
+    window.$docsify = {
+      loadSidebar: true,
+      markdown: {
+        smartypants: true,
+        renderer: {
+          code(block, lang) {
+            return block && lang === 'playground'
+              ? `<code-playground>${block}</code-playground>`
+              : block;
+          }
+        }
+      },
+      name: 'Accelint Standard Toolkit',
+      repo: 'https://github.com/gohypergiant/standard-toolkit',
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="https://cdn.jsdelivr.net/npm/[email protected]/components/prism-typescript.js"></script>
+</body>
+</html>
diff --git a/documentation/adrs/001-documentation-tool.md b/documentation/adrs/001-documentation-tool.md
@@ -0,0 +1,55 @@
+# Choosing a Documentation Tool
+
+We want to offer exemplary DevTK documentation for current and future users to learn and discover the functionalities contained.
+
+## Goals
+
+  1. Docblocks inside the codebase
+      - These are inline comments documenting the structure, usage, and behavior of specific functions, classes, and modules.
+      - Docblocks are helpful for users and maintainers as they provide information in close to where the code is being used.
+  2. Markdown outside of the codebase
+      - Markdown files outside the codebase can contain additional documentation such as high-level architectural decisions, design intentions, and contextual explanations.
+  3. Easy maintenance
+      - There are at least two aspects to maintenance: maintaining the documentation to keep it accurate, and generating the tool used to browse the documentation.
+      - The Docblocks are helpful but including exhaustive documentation in the codebase will become burdensome and avoided.
+      - Maintaining two (or more) sources of truth for any content will mean that it will become out of date very easily and quickly; the only thing worse than no documentation is bad/incorrect documentation.
+      - We will have plenty of work building the modules we don't need the additional responsibility of keeping a whole other project - the documentation site - up to date and accurate.
+  4. No-setup playgrounds
+      - Where possible, for each module, there could be an interactive component that would allow users to experiment with the codebase from within the documentation site itself.
+
+## Tools
+
+Tool         | Latest Release | Stand-alone | Static | Build
+------------ | -------------- | :---------: | :----: | :---:
+[RSPress]    |                | Yes         |        | Yes
+[Vocs]       |                | Yes         |        | Yes
+[Docusaurus] |                | Yes         |        | Yes
+[TSDoc]      |                | Yes         |        | Yes
+[TypeDoc]    |                | Yes         |        | Yes
+[Docz]       |                | Yes         |        | Yes
+[TS-Docs]    |                | Yes         |        | Yes
+[JSDoc]      |                | Yes         |        | Yes
+[FumaDocs]   |                | Yes         |        | Yes
+[Slate]      |                | Yes         |        | Yes
+[Docsify]    |                | No          |        | No
+[Startlight] |                | Yes         |        | Yes
+
+### Criteria
+
+- Latest Release - how current is the tool
+- Stand-alone - does this create another project to keep in sync
+- Static - can be hosted statically
+- Build - requires a build step to generate the pages
+
+[RSPress]: https://rspress.dev/
+[Vocs]: https://vocs.dev/
+[Docusaurus]: https://docusaurus.io/
+[TSDoc]: https://tsdoc.org/
+[TypeDoc]: https://typedoc.org/
+[Docz]: https://www.docz.site/
+[TS-Docs]: https://ts-docs.github.io/ts-docs/
+[JSDoc]: https://jsdoc.app/
+[FumaDocs]: https://fumadocs.vercel.app/
+[Slate]: https://slatedocs.github.io/slate/#introduction
+[Docsify]: https://docsify.js.org/#/
+[Startlight]: https://starlight.astro.build/
diff --git a/package.json b/package.json
@@ -24,6 +24,7 @@
     "docs": "turbo docs",
     "format": "pnpm biome format . --write",
     "indexer": "turbo index",
+    "docsify": "docsify serve ./docs",
     "license": "pnpm zx scripts/license.mjs",
     "lint": "turbo lint",
     "lint:fs": "pnpm ls-lint",
@@ -37,6 +38,7 @@
     "@changesets/cli": "^2.27.9",
     "@ls-lint/ls-lint": "2.3.0-beta.1",
     "@swc/core": "^1.7.36",
+    "docsify-cli": "^4.4.4",
     "rimraf": "^5.0.10",
     "syncpack": "^13.0.0",
     "taze": "^0.17.2",