save point

gohypergiant · Dec 6, 2024 · f72a125 · f72a125
1 parent 9674cae
commit f72a125
Show file tree

Hide file tree

Showing 11 changed files with 1,286 additions and 9 deletions.
diff --git a/.ls-lint.yml b/.ls-lint.yml
@@ -28,5 +28,6 @@ ignore:
   - '**/build'
   - '**/coverage'
   - '**/dist'
+  - '**/docs'
   - '**/documentation'
   - '**/node_modules'
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,3 @@
+# Accelint Standard Toolkit
+
+A documentation site (in progress).
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,69 @@
+# 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.
+  5. Limits
+      - dont want to replace training suite
+      - dont want to replace code comments
+
+## Tools
+
+Tool         | Latest    | Releases  | Contributors | Build | Setup | Run | React
+------------ | --------- | --------- | ------------ | ----- | ----- | --- | -----
+[Docsify]    | 1 day     | 14        | 183          | None  | Easy  | Ext | Ext
+[Docusaurus] | 2 hours   | 148       | 1175         | Yes   |       |     |
+[Docz]       | 2 years   | 127       | 134          | Yes   |       |     |
+[FumaDocs]   | 2 hours   | 673*      | 43           | Yes   |       |     |
+[JSDoc]      | 2 days    | 12        | 83           | Gen   | Easy  | No  |
+[RSPress]    | 2 days    | 115       | 97           | Yes   |       |     |
+[Startlight] | 2 days    | 134       | 228          | Yes   |       |     |
+[TS-Docs]    | 2 years   | 16        | 134          | Yes   | Hard  |     |
+[TypeDoc]    | 2 days    | 224       | 227          | Yes   |       |     |
+[Vocs]       | 2 months  | 468       | 21           | Yes   |       |     |
+_            |           |           |              |       |       |     |
+[Slate]      | 10 months | 28        | 126          | Yes   | Hard  |     |
+[TSDoc]      | 2 weeks   | ???       | 1            | Yes   | Hard  | No? | No?
+
+### Criteria
+
+- __Build__ - requires a build step to generate the pages
+  - Yes - will be an additional step in CI
+  - Gen - will be an additional step in CI but very basic generation from docblocks
+  - None - will not require a build or generation step
+- __Contributors__ - number of people contributing
+- __Latest__ - most recent change in github (_at time of collection_)
+- __React__ - renders react components (e.g. from design system)
+  - Yes - native support
+  - Ext - will require an extension/plugin
+- __Releases__ - number of "releases" or production deployments
+- __Run__ - supports interactive code examples
+  - Yes - native support
+  - Ext - will require an extension/plugin
+- __Setup__ - ease of getting it running: easy, or hard
+
+[Docsify]: https://docsify.js.org/#/
+[Docusaurus]: https://docusaurus.io/
+[Docz]: https://www.docz.site/
+[FumaDocs]: https://fumadocs.vercel.app/
+[JSDoc]: https://jsdoc.app/
+[RSPress]: https://rspress.dev/
+[Slate]: https://slatedocs.github.io/slate/#introduction
+[Startlight]: https://starlight.astro.build/
+[TS-Docs]: https://ts-docs.github.io/ts-docs/
+[TSDoc]: https://tsdoc.org/
+[TypeDoc]: https://typedoc.org/
+[Vocs]: https://vocs.dev/
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",
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Accelint Standard Toolkit

		A documentation site (in progress).