feat(docs): add hash-based caching for API docs generation

[nathan-weinberg]

What does this PR do?

Add caching layer to skip regenerating API documentation when OpenAPI specs haven't changed. This significantly speeds up documentation builds by avoiding redundant work.

The docusaurus-plugin-openapi-docs was regenerating 148 API documentation files from scratch on every build, generating code samples in 4 languages for each endpoint. This was leading to extremely long build times.

Changes

• Add docs/scripts/gen-api-docs.js with SHA-256 hash-based caching
• Add scripts/build-docs.sh wrapper script for building docs
• Update docs/package.json with new npm scripts for selective generation
• Support parallel generation with --parallel flag
• Support individual spec generation (stable/experimental/deprecated)

Performance Impact

Scenario	Before	After
Specs unchanged	~minutes	instant (skipped)
All specs changed (sequential)	~5s	~5s
All specs changed (parallel)	~5s	~3s
Only one spec changed	~5s (all regenerated)	~2s (only changed spec)

New npm Scripts

Script	Description
npm run gen-api-docs	Generate API docs with caching (skips if specs unchanged)
npm run gen-api-docs:force	Force regeneration of all API docs
npm run gen-api-docs:parallel	Generate API docs in parallel
npm run gen-api-docs:stable	Generate only stable API docs
npm run gen-api-docs:experimental	Generate only experimental API docs
npm run gen-api-docs:deprecated	Generate only deprecated API docs

Closes #4315

Test Plan

• Verify caching skips generation when specs haven't changed
• Verify parallel mode works correctly
• Verify individual spec generation works
• Test in https://github.com/llamastack/llamastack.github.io workflow

🤖 Generated with Claude Code

[cdoern]

hmmm, I wonder if this is worth the tradeoff of having all of these new files in the codebase, will see what others think though

the issue talks about an incremental build, so I guess this solves that, right? I am just not sure if there is a better way to do an incremental build?

[nathan-weinberg]

hmmm, I wonder if this is worth the tradeoff of having all of these new files in the codebase, will see what others think though

the issue talks about an incremental build, so I guess this solves that, right? I am just not sure if there is a better way to do an incremental build?

Def open to other concrete ideas - FWIW, note

This only adds a bit less than 3MB of size to the repo

[raghotham]

I'd rather not add 3MB to the main repo. It seems like the following should be possible. @nathan-weinberg can you check?

1. create a new repo for doc previews (maybe try out with llama-stack-ops for now (we are planning on deprecating in the future anyway - it might take a bit to create a new repo)
2. use workflow_call on every PR in /llama-stack to create a reviewable docs link in the new repo
3. use workflow_call to remove the preview on PR close

[nathan-weinberg]

I'd rather not add 3MB to the main repo. It seems like the following should be possible. @nathan-weinberg can you check?

1. create a new repo for doc previews (maybe try out with llama-stack-ops for now (we are planning on deprecating in the future anyway - it might take a bit to create a new repo)

2. use workflow_call on every PR in /llama-stack to create a reviewable docs link in the new repo

3. use workflow_call to remove the preview on PR close

I will take these actions - in the meantime, going to see if there are any other small steps I can take to reduce the local time here as well - otherwise I will close this PR.