Skip to content

docs: share guides and execute examples across ports - #195

Draft
lan17 wants to merge 7 commits into
mainfrom
codex/shared-port-docs
Draft

lan17 wants to merge 7 commits into
mainfrom
codex/shared-port-docs

Conversation

@lan17

@lan17 lan17 commented Sep 22, 2026

Copy link
Copy Markdown
Owner

The documentation currently describes shared behavior through TypeScript-only examples and vocabulary. This change gives TypeScript, Go, and Rust readers the same feature guides, with a remembered language choice selecting native examples, binding notes, and API links.

  • Migrate the existing guides while preserving their URLs and anchors; add concise native setup/idiom guides and a contributor workflow in docs/authoring.md.
  • Import request-scope, sparse-policy, and tracked-invalidation scenarios from executable files in all three ports. Assertions check observable source calls and reuse; invalidation first proves a real Redis hit, then a refetch. TypeScript checks the packed package, Go runs with race detection, and Rust explicitly runs its Redis scenario in CI.
  • Generate TypeDoc, Go package documentation, and rustdoc from the checkout, plus a behavior catalogue from the existing semantic inventory. Generated output stays out of Git.
  • Check source-region existence, all-port coverage for imported shared scenarios, internal links/anchors, and native-reference navigation. Extend the existing source audit to include authored native guides.

Validation: make check-ts, make check-go, make check-rust, make audit, and the complete docs build pass locally. All nine new scenarios passed against real Redis. Browser checks verified language switching, persistence across navigation/reload, native-guide routing, and generated Go/Rust references. Independent review findings were fixed, including VitePress intercepting static API links.

The docs build now needs the pinned Go and Rust toolchains. Advanced inline API fragments are labeled excerpts; this does not claim they all execute or that every existing public doc comment is complete. No cache behavior, Quint model, or conformance assertion was changed. Full exploration and mutation campaigns were not rerun for this documentation/tooling change.

Refs #166.

— Levicus

Comment thread scripts/check-docs.mjs Fixed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants