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

[bashir1738]

• 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

[Miracle656]

The TypeDoc workflow cleanup here is good (npm ci, gh-pages@v4, keep_files). Two things to trim before it lands:

1. It deletes docs/cookbook/portfolio.md and dashboard-preview.jpg, but the example they document (examples/portfolio-dashboard) is still in the repo — so this removes live docs. Please drop those deletions unless the example is also going away.
2. It removes the npm run docs:openapi step from the workflow. If the OpenAPI reference should still be published, keep that step (or explain why it's no longer needed).

Scope it to just the TypeDoc CI change and I'll merge.

[Miracle656]

Apologies for the wait on this one.

Two things to resolve, and one of them I would like explained before anything merges.

Unexplained deletions

This PR deletes two files that are live on main:

docs/cookbook/portfolio.md          (-52)
docs/cookbook/dashboard-preview.jpg (binary)

Neither is mentioned in the description, which is entirely about adding TypeDoc publishing. Removing documentation inside a CI PR is the kind of thing that goes unnoticed in review and is then hard to trace later.

If they are genuinely obsolete, say so and it is fine. If they were caught by a docs/ clean-up while wiring TypeDoc's output directory, they should come back — and the TypeDoc config should be pointed somewhere that does not collide with hand-written docs.

TypeDoc already exists

The description reads "Add typedoc.json" and "Add .github/workflows/typedoc.yml", but both are already on main — the diff is +6/-1 and +18/-7 against existing files, and a TypeDoc workflow already runs green on main. Something landed in the interim.

So this is a refinement of existing config rather than new capability, which is fine — but the description should say what it improves over what is there, because right now a reviewer cannot tell what problem is being fixed.

What would make this mergeable

1. Restore the two docs/cookbook/ files, or explain why they should go
2. Update the description to state what changes relative to the existing TypeDoc setup
3. Confirm the gh-pages publish does not overwrite anything hand-written already served from that branch

Worth noting peaceiris/actions-gh-pages will happily replace the whole branch contents depending on configuration — that is worth double-checking given point 1.

Not closing it. If the cookbook deletion was accidental this is a quick fix; if you would rather drop the PR after the delay, that is fair too.

[Miracle656]

Approved and merging — I fixed the cause of the deletions myself (6ca3d24), since the wave has closed.

I owe you an answer to my own question. I asked why this PR deleted docs/cookbook/portfolio.md and dashboard-preview.jpg. It wasn't an editorial decision, and it wasn't carelessness — typedoc.json on main sets "out": "docs", and TypeDoc empties its output directory before generating. Running npx typedoc locally wiped docs/cookbook/, and the deletions came along in the diff. You didn't delete those files; the config did.

So the real finding in this PR is a live bug on main, and it had just got considerably worse: #157 removed docs/ from .gitignore a few hours ago. Before that, TypeDoc quietly destroying docs/ was invisible to git. After it, 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. Your PR is what surfaced that, one merge before it bit someone.

The fix:

• typedoc.json: out → docs/api, so generated and hand-written docs stop sharing a directory. I kept your name, entryPointStrategy and navigationLinks additions.
• Restored the two cookbook files from main.
• Restored the npm run docs:openapi step your workflow rewrite dropped. Without it the published site serves a stale OpenAPI spec — and since nothing else reads that file, nothing would have flagged it.
• .gitignore now ignores docs/openapi.json and docs/api/ specifically, rather than docs/ wholesale: the generated artefacts, not the guides.

Verified by running it, which felt like the only honest way to check a fix for "the tool deletes things":

docs/ before:  backup-restore.md  cookbook/  DUAL_NETWORK.md  event-reference.md  openapi.json
$ npx typedoc  →  html generated at ./docs/api
docs/ after:   api/  backup-restore.md  cookbook/  DUAL_NETWORK.md  event-reference.md  openapi.json

Two of your changes I kept deliberately, because they are improvements:

• npm ci without the || npm install fallback. That fallback silently papers over a lockfile desync by resolving a different dependency tree than the lockfile describes — which is how a CI job starts passing on dependencies nobody chose. Failing is the right behaviour.
• peaceiris/actions-gh-pages@v4 and keep_files.

On the description: the workflow and typedoc.json did already exist on main by the time I looked, so this reads as a refinement rather than the new capability it describes. That's a race, not a mistake — but it is why I could not tell what problem was being solved, and the answer turned out to be a good one.

Thanks — this one was more valuable than it looked.