save point

gohypergiant · Dec 18, 2024 · 82568ec · 82568ec
1 parent f72a125
commit 82568ec
Show file tree

Hide file tree

Showing 11 changed files with 65 additions and 1,235 deletions.
diff --git a/.ls-lint.yml b/.ls-lint.yml
@@ -28,6 +28,5 @@ 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
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
diff --git a/docs/constants.md b/docs/constants.md
diff --git a/docs/favicon.ico b/docs/favicon.ico
diff --git a/docs/geo.md b/docs/geo.md
diff --git a/docs/index.html b/docs/index.html
diff --git a/documentation/adrs/001-documentation-tool.md b/documentation/adrs/001-documentation-tool.md
@@ -20,23 +20,36 @@ We want to offer exemplary DevTK documentation for current and future users to l
       - dont want to replace training suite
       - dont want to replace code comments
 
+### Recommendation
+
+>[!IMPORTANT]
+>The best option at this time is [RSPress].
+>
+> - Active development
+> - Future focused tech stack
+> - Tech stack alignment (with our own)
+
 ## 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?
+Tool         | Latest    | Releases  | Contributors | Build | Setup | React | Customization | Disqualifier
+:----------- | --------- | --------- | ------------ | ----- | ----- | ----- | ------------: | ------------
+[Docusaurus] | 2 hours   | 148       | 1175         | Yes   |       | Yes   | Moderate      |
+[FumaDocs]   | 2 hours   | 673*      | 43           | Yes   |       | Yes   | Moderate      |
+[RSPress]    | 2 days    | 115       | 97           | Yes   | Easy  | Yes   | Moderate      |
+[Startlight] | 2 days    | 134       | 228          | Yes   |       | Yes   | Moderate      |
+[Vocs]       | 2 months  | 468       | 21           | Yes   |       | Yes   | Moderate      |
+_            |           |           | Disqualified |       |       |       |               | _
+[Docsify]    | 1 day     | 14        | 183          | None  | Easy  | Ext   | Minimal       | Burden of extension
+[Docz]       | 2 years   | 127       | 134          | Yes   |       | Yes   | Moderate      | Age without update
+[JSDoc]      | 2 days    | 12        | 83           | Gen   | Easy  | No    | Extensive     | Burden of extension
+[MkDocs]     | 1 month   | 15        | 244          | Yes   |       |       | Extensive     | Burden of extension
+[Pandoc]     | 1 day     | 140       | 522          | Yes   | Hard  | Ext   | Extensive     | Burden of extension
+[Slate]      | 10 months | 28        | 126          | Yes   | Hard  | No?   | Extensive     | Burden of extension
+[TS-Docs]    | 2 years   | 16        | 1            | Yes   | Hard  | No    | Extensive     | Burden of extension
+[TSDoc]      | 2 weeks   | ???       | 36           | Yes   | Hard  | No?   | Extensive     | Burden of extension
+[TypeDoc]    | 2 days    | 224       | 227          | Yes   |       | No?   | Moderate      | Additional guides support
+
+_Many of the listed tools are quite comparable so choosing one over the other has a narrow margin. However, some are clearly less capable or are less aligned with the goals and desired development practices than others._
 
 ### Criteria
 
@@ -45,21 +58,46 @@ _            |           |           |              |       |       |     |
   - 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
+- __Customization__ - the level needed to accomplish our goals
+  - Minimal
+  - Moderate
+  - Extensive
 - __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
 
+### Notes
+
+#### Docsify
+
+This tool was the easiest to get running and extend; less than a day to start and extend. The biggest limitation to this as a solution is that all execution is done at runtime in the users/viewers browser; this would likely limit the potential integrations we would have available for development.
+
+#### RSPress / Vocs
+
+These tools are robust and fairly mature. Getting up and running with the basics is straightforward. Their offerings are very similar and their limitations are also similar.
+
+RSPress lacks the ability to display a sandbox for a typescript module (and its dependencies) natively; however, there is support for displaying an interactive React.js component preview. A typescript solution is not too far off, with some work, using something like StackBlitz or Sandpack SDKs; it will take a fair amount of effort to get up and running and then long-term maintenance.
+
+#### ts-docs
+
+An interesting feature of ts-docs is native support for unit testing the code examples in the documentation to ensure consistency with the codebase.
+
+#### TypeDoc
+
+An interesting divergent pattern of this tool is explicit linking to external documentation in the docblock comment in code. Also, TypeDoc doesn't seem to support React components; at least I wasn't able to quickly find a reference to what I would expect.
+
+The limitation that excludes TypeDoc from further consideration is that it does not support the desire for additional content outside of the structure of a code file. Meaning that if we want pages in the documentation site that aren't generated as a result of a code file there is some work required to accomplish this.
+
 [Docsify]: https://docsify.js.org/#/
 [Docusaurus]: https://docusaurus.io/
 [Docz]: https://www.docz.site/
 [FumaDocs]: https://fumadocs.vercel.app/
 [JSDoc]: https://jsdoc.app/
+[MkDocs]: https://www.mkdocs.org/getting-started/
+[Pandoc]: https://pandoc.org/
 [RSPress]: https://rspress.dev/
 [Slate]: https://slatedocs.github.io/slate/#introduction
 [Startlight]: https://starlight.astro.build/

diff --git a/package.json b/package.json
@@ -24,7 +24,6 @@
     "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",
@@ -38,7 +37,6 @@
     "@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",