jason810496 opened a new pull request, #70812: URL: https://github.com/apache/airflow/pull/70812
- **next:** automate the docs publish process for TS-SDK API referecnce. ## Why The upcoming TS-SDK package has a public API that is annotated with JSDoc/TSDoc but has no rendered API reference. This adds one, built with [pyodide/sphinx-js](https://github.com/pyodide/sphinx-js) (TypeDoc-backed) and wired into the existing `build-docs` and `publish-docs` pipelines next to `task-sdk`. ## How - New `ts-sdk/docs/` Sphinx tree that mirrors `task-sdk/docs/`, swapping `autoapi` for `sphinx-js` since the source is TypeScript. - A single root entry point (`src/index.ts`) is fed to TypeDoc, so its reachability analysis documents exactly the public surface and excludes the generated/internal modules. - The TypeDoc toolchain is isolated in `ts-sdk/docs/package.json` + `package-lock.json` and pinned deliberately: - sphinx-js 5.0.3 needs TypeDoc 0.25 (its plugin breaks on TypeDoc 0.28's internal API). - TypeDoc 0.25 ships TypeScript 5.4, which rejects the SDK's `es2023` target, so `ts-sdk/docs/tsconfig.json` is a standalone config forcing `es2022` for the parse-only pass. - `ts-sdk/docs/sphinxJsConfig.mjs` flattens TSDoc `{@link}` inline tags to plain text, which sphinx-js cannot otherwise render. - `AirflowDocsBuilder` installs the pinned toolchain with `npm ci` (reproducible) on demand before the sphinx run, so `build-docs ts-sdk` works wherever Node is available (already present in the docs CI image). A failed install returns a `DocBuildError` for that package rather than aborting the whole run. - Adding `sphinx-js` pulls `parsimonious` and requires `cattrs < 25`, so `uv.lock` downgrades `cattrs` 26.1.0 to 24.1.3 (sphinx-js declares `cattrs` as a dependency). ## Verification <img width="1508" height="855" alt="Screenshot 2026-07-31 at 2 22 40 PM" src="https://github.com/user-attachments/assets/cd08d391-c78c-422e-ad88-481fc8bc30df"; /> <img width="1512" height="857" alt="Screenshot 2026-07-31 at 2 22 52 PM" src="https://github.com/user-attachments/assets/ef1a1771-46fe-4065-9c2a-bd403d9b5546"; /> ## Notes for reviewers - The TypeDoc `0.25` pin is a version cap forced by sphinx-js 5.0.3. Per the repo convention for capped dependencies, this warrants a GitHub tracking issue (to bump TypeDoc/TypeScript once sphinx-js supports TypeDoc 0.28). - Another direction is we could use TypeDoc only without sphinx extension like Java-SDK did. --- ##### Was generative AI tooling used to co-author this PR? - [x] Yes, with help of Claude Code Opus 4.8 following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
