ci(docs): auto-publish TypeDoc API reference to gh-pages (#158)

* ci(docs): auto-publish TypeDoc API reference to gh-pages

- Add typedoc.json with entryPoints covering public modules
- Add .github/workflows/typedoc.yml to run on every main push
- Push generated HTML output to gh-pages via peaceiris/actions-gh-pages
- Add README link to hosted docs URL

Closes #62

* Point TypeDoc at docs/api instead of docs, and restore what it deleted

The two deleted files were not an editorial decision. typedoc.json set
"out": "docs", and TypeDoc empties its output directory before generating,
so running it locally wiped docs/cookbook/ and the deletions were picked up
as part of the diff.

That is a live bug on main, and it just got worse: #157 removed docs/ from
.gitignore, so the next person to run npx typedoc would have deleted
DUAL_NETWORK.md, backup-restore.md, event-reference.md and the cookbook, and
git would have staged all of it.

- typedoc.json: out -> docs/api, so generated and hand-written docs no longer
  share a directory. Kept this PR's name, entryPointStrategy and
  navigationLinks additions.
- Restored docs/cookbook/portfolio.md and dashboard-preview.jpg from main.
- Restored the npm run docs:openapi step the workflow rewrite dropped. Without
  it the published site keeps a stale OpenAPI spec, and nothing else reads
  that file so nothing would have flagged it.
- .gitignore ignores docs/openapi.json and docs/api/ specifically, rather than
  docs/ wholesale — the generated artefacts, not the guides.

Kept from this PR: npm ci without the || npm install fallback (a lockfile
desync should fail rather than silently resolve differently),
peaceiris/actions-gh-pages@v4, and keep_files.

Verified by running npx typedoc: output lands in docs/api and every
hand-written doc is still there afterwards.

---------

Co-authored-by: Miracle656 <iupacnumen2020@gmail.com>

Author: bashir1738

.github/workflows/typedoc.yml

@@ -9,21 +9,41 @@ jobs:
     name: Generate & publish API docs
     runs-on: ubuntu-latest
     permissions:
-      # peaceiris/actions-gh-pages pushes to the gh-pages branch, which needs
-      # write access to repo contents. The default GITHUB_TOKEN is read-only.
+      # peaceiris/actions-gh-pages needs write access to push to the gh-pages branch.
       contents: write
     steps:
       - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
           cache: npm
-      - run: npm ci || npm install
-      - run: npx prisma generate
-      - run: npm run docs:openapi
-      - run: npx typedoc
+
+      # Install deps (Prisma client is a peer of typedoc-plugin-* if ever added)
+      - name: Install dependencies
+        run: npm ci
+
+      # Prisma generate is required so TypeDoc can resolve @prisma/client types
+      # when it processes db.ts and other modules that import from it.
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      # Regenerates docs/openapi.json, which is published alongside the
+      # TypeDoc output. Dropping it would leave the hosted site with a stale
+      # OpenAPI spec — silently, since nothing else reads that file.
+      - name: Generate OpenAPI document
+        run: npm run docs:openapi
+
+      # TypeDoc writes to docs/api (see typedoc.json). It empties its output
+      # directory first, so it must NOT point at docs/ itself — that is what
+      # deleted docs/cookbook in an earlier revision of this PR.
+      - name: Build TypeDoc HTML
+        run: npx typedoc
+
       - name: Deploy to gh-pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs
+          # Overwrite only the docs output; keep any other files already on the branch.
+          keep_files: true

.gitignore

@@ -1,7 +1,9 @@
 node_modules/
 dist/
-# Generated by `npm run docs:openapi` alongside the tracked root openapi.json.
+# Generated docs output. docs/ itself is tracked (hand-written guides live
+# there); only the generated artefacts inside it are ignored.
 docs/openapi.json
+docs/api/
 .env
 *.env.local
 bench/results.json

typedoc.json

@@ -1,4 +1,5 @@
 {
+  "name": "Wraith — API Reference",
   "entryPoints": [
     "src/index.ts",
     "src/api.ts",
@@ -9,7 +10,8 @@
     "src/events.ts",
     "src/indexer.ts"
   ],
-  "out": "docs",
+  "entryPointStrategy": "resolve",
+  "out": "docs/api",
   "theme": "default",
   "readme": "README.md",
   "includeVersion": true,
@@ -18,5 +20,8 @@
   "excludeExternals": true,
   "hideGenerator": false,
   "sort": "source-order",
-  "searchInComments": true
+  "searchInComments": true,
+  "navigationLinks": {
+    "GitHub": "https://github.com/Miracle656/wraith"
+  }
 }