WIP Upgrade Docs to Docusaurus#2911
Draft
davidgamero wants to merge 11 commits into
Draft
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
Contributor
|
[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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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