Add TypeDoc documentation generation

Add `npm run docs` to generate documentation in `./docs/` for all of our
package groups as well as a static page on "Why Ninjutsu Build?".

This will be a good starting point to review and improve the
documentation as a whole and publish it to Github pages.

.github/workflows/ci.yaml

@@ -26,3 +26,4 @@ jobs:
     - run: cd configure && npm ci
     - run: npm run configure
     - run: ninja -k 0
+    - run: npm run docs

.gitignore

@@ -4,4 +4,3 @@ node_modules
 .vscode
 .builddir
 build.ninja
-

configure/package.json

@@ -13,6 +13,7 @@
     "@types/node": "^20.12.7",
     "@types/toposort": "^2.0.7",
     "glob": "^10.3.10",
-    "is-ci": "^3.0.1"
+    "is-ci": "^3.0.1",
+    "typedoc": "^0.26.3"
   }
 }

configure/typedoc.jsonc

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "name": "@ninjutsu-build",
+  "out": "../docs",
+  "entryPoints": [
+    "../guides",
+    "../packages/biome",
+    "../packages/bun",
+    "../packages/core",
+    "../packages/esbuild",
+    "../packages/node",
+    "../packages/tsc"
+  ],
+  "entryPointStrategy": "packages"
+}

guides/Why Ninjutsu Build.md

@@ -0,0 +1,16 @@
+# Why Choose Ninjutsu Build?
+
+Ninjutsu Build is a collection of packages designed to help create a `.ninja` file. This file outlines all dependencies between inputs and outputs in your projects, along with the necessary shell commands to generate those files.
+
+The [`ninja`](https://ninja-build.org/) executable reads this file. Known for its speed, Ninja is used to build large C++ applications like [Chromium](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/build_instructions.md#setting-up-the-build) and [LLVM](https://www.llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm).
+
+Using Ninjutsu Build, you orchestrate your build process with JavaScript while executing it with `ninja`. This approach combines JavaScript's flexibility with the speed of a native build orchestrator. Modern tools for transpiling TypeScript to JavaScript allow you to separate typechecking and type generation from running tests, providing faster feedback during development.
+
+After making changes to files, `ninja` will identifies which output files are outdated and determines the quickest way to update them. For instance, the Ninjutsu `node` plugin tracks all JavaScript files imported during each test run, so after modifying one file, `ninja` will only rerun the subset of tests that imported that file.
+
+Consider using Ninjutsu Build if:
+
+  * You are dissatisfied with the large number of `package.json` scripts.
+  * You have non-standard build steps.
+  * You already use a JavaScript/TypeScript script to orchestrate your build but seek improved performance or better dependency tracking.
+  * You want to integrate formatting, linting, transpiling, and/or typechecking into the same build command.

guides/package.json

@@ -0,0 +1,2 @@
+{
+}

guides/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "Guides",
+    "projectDocuments": ["./*.md"]
+}

package.json

@@ -10,6 +10,7 @@
   ],
   "scripts": {
     "build": "ninja",
-    "configure": "node configure/configure.mjs"
+    "configure": "node configure/configure.mjs",
+    "docs": "cd configure && npx typedoc"
   }
 }

packages/biome/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "biome",
+    "entryPoints": ["./src/biome.ts"],
+}

packages/bun/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "bun",
+    "entryPoints": ["./src/bun.ts"],
+}

packages/core/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "core",
+    "entryPoints": ["./src/core.ts"],
+}

packages/esbuild/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "esbuild",
+    "entryPoints": ["./src/esbuild.ts"],
+}

packages/node/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "node",
+    "entryPoints": ["./src/node.ts", "./src/runtime.cts"],
+}

packages/tsc/typedoc.jsonc

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "name": "tsc",
+    "entryPoints": ["./src/tsc.ts"]
+}