WIP Upgrade Docs to Docusaurus#2911
Conversation
…traction - Scaffold Docusaurus 3.x with TypeScript in website/ - Strip blog, configure for Kubernetes JS client project - Add tsconfig.docs.json excluding src/gen/** and src/api.ts - Create transform script test fixtures with edge cases - Add API group extraction script from swagger.json (65 APIs mapped) Wave 1 complete (Tasks 1-4)
…d local search Wave 2 implementation: - Task 5: Gen docs transform script (6 transforms, 65 files) - Task 6: docusaurus-plugin-typedoc for 18 SDK entry points - Task 7: Sidebar with SDK Reference + API Reference categories - Task 8: @easyops-cn/docusaurus-search-local plugin Fixes applied during verification: - TypeDoc output path corrected to docs/sdk (was sdk/) - mdxOptions format:detect to treat .md as plain markdown - Footer cleanup regex broadened to catch all variations - Stale tutorial scaffold docs removed
…nding page Task 9: prebuild/prestart hooks run transform-gen-docs.mjs automatically Task 9: .gitignore excludes docs/api-reference/ and docs/sdk/ (generated) Task 9: untrack generated docs from git (regenerated on build) Task 11: custom landing page with install command and quick links Task 11: intro.md with KubeConfig example and compatibility table
Task 10: Docusaurus versioning with current (2.0.0 Next) and 2.0.0 stable - versions.json registry - versioned_docs/version-2.0.0/ snapshot (165 files) - versioned_sidebars/version-2.0.0-sidebars.json - docusaurus.config.ts lastVersion + version labels - 1.4.0 deferred (tag lacks pre-generated docs)
Task 12: deploy-docs-v2.yml for Docusaurus gh-pages deploy Task 13: root .gitignore + README updated for Docusaurus docs Task 14: release.yml version snapshot step for auto-versioning
- Add 5 example pages (basic-operations, pod-operations, watching-and-caching, kubectl-equivalents, advanced) pulling from real source files - Remove v2.0.0 versioned snapshot in favor of unversioned 'next' docs - Add remark plugin for example links, SDK flatten plugin, model generation - Update transform and flatten scripts with improved API doc generation - Clean up config: add remarkPlugins, format detection, custom 404 - Update CI workflow and README with docs instructions
Collapses the lockfile in PR diffs and excludes it from GitHub language statistics, so the ~4.4k of reviewable changes aren't buried under the ~19k-line generated lockfile.
kubernetes-prow
Bot
added
the
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: davidgamero The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
kubernetes-prow
Bot
added
approved
Docs are served at routeBasePath '/', but @easyops-cn/docusaurus-search-local defaults docsRouteBasePath to '/docs'. The mismatch meant zero documents were indexed and no search-index.json was emitted, so the search box spun forever. Set docsRouteBasePath: '/' to match. Verified the index now contains real terms (KubeConfig, Watch, Pod, Informer).
Per k8s policy, action refs must be pinned to full-length commit SHAs rather than version tags. Pins checkout, setup-node, and the gh-pages deploy action to the same SHAs already used by the sibling workflows.
|
Looks like there are some bad links, so CI/CD is failing. |
The Validate links step ran hyperlink against docs/build directly, but the site baseUrl is /javascript/, so every internal link is emitted as /javascript/... . hyperlink treats the target dir as server root, so those site-absolute links resolved to a nonexistent /javascript prefix and produced ~21k false 'bad link' errors (0 bad anchors). Stage the build under a javascript/ subdir and point hyperlink at the parent so links resolve. Also drop --sources (reporting-only, does not affect pass/fail) and gitignore the _linkcheck scratch dir.
|
updated to link generated docs dir so absolute links can be validated |
@davidgamero can you elaborate how this works? What is the "GH Action" method? |
there are 2 ways to publish to github pages static sites:
Configuring a publishing source for your GitHub Pages site current flow is as follows
step 2 is blocked by the CLA check or branch protections mentioned in #2908 the new flow replaces this step with the actions/deploy-pages github action to publish without using a branch to store the contents, instead a github artifact is uploaded with the static site content. as no branch push is required, the CLA and branch rules no longer block the doc publishing. additionally, the docs are generated from the types during the workflow run, so the full docs content is not pushed in source control every time, it instead exists as a function of the source, and in an artifact this requires toggling a setting on the repo for under "Pages" |
3 participants
will attach generated output to test on my forkdeployed live version on fork https://davidgamero.github.io/javascript/
the current publish pipeline uses the gh-pages branch which gets blocked by CLA check. we can change repo to use "GH Action" method for gh pages publishing to resolve this issue
addressing #2908
recognizing line count is still large. package lock is 19k making diff look much bigger