feat: assemble the open-source pages from lancedb/lancedb - #355
Open
jackye1995 wants to merge 2 commits into
Open
feat: assemble the open-source pages from lancedb/lancedb#355jackye1995 wants to merge 2 commits into
jackye1995 wants to merge 2 commits into
Conversation
The pages describing the open-source client now live in that repository, beside the code, and are assembled from there. This repository keeps what it still owns — the Geneva pages until Stage G replaces them, the generated dataset cards, the OpenAPI spec, and the Enterprise pages until they move to sophon. Navigation is the interesting part. It is authored once, in the root that owns the pages, so that root can also be served on its own — a contributor previews the open-source documentation with `mint dev` and no second checkout. Everything this repository still holds is contributed as a fragment that says where each entry belongs: the chain of groups above it and the sibling it follows. Appending was not good enough, because sidebar order is what a reader navigates by, and appending dropped Geneva below Support and Datasets past Use Cases. `scripts/split_nav.py` produced that fragment by walking the original navigation rather than by hand, which is how the six entries stayed six rather than ninety-seven. A5 reuses it when the Enterprise pages move. Three things had to match exactly, and each was found by the harness: The `openapi` block names a spec file this repository owns, and Mintlify refuses to build at all when it is missing — so it is lifted out of the base navigation and restored by the fragment. Key order in `docs.json` is load-bearing. Mintlify hashes its CSS and JS bundles from those bytes, so moving `navigation` renamed every asset on every page. `ensure_ascii` likewise: the banner text carries an em-dash, and escaping it differently changed the same bytes. CI now checks out lancedb/lancedb at main and assembles twice, comparing the two. The site no longer exists as a single tree anywhere, so a direct comparison against `docs/` is not available; determinism is what the comparison can still establish. Verified: the assembled tree is byte-identical to the one it replaces.
#350 was merged into deploy-freeze while the freeze was in effect, so the fix is live but absent from main and would have been lost at cutover: the redirect for /hybrid-search and the removal of a redundant layers diagram from the Enterprise architecture page. Redirects are now owned by this repository's navigation fragment, so that is where the redirect goes. The diagram removal is applied as a patch rather than by taking the whole file from deploy-freeze, which would have reverted that page's anchors along with it. Anything else that lands on deploy-freeze during the freeze needs the same treatment — it is the branch production serves, and it does not flow back.
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
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.
A3 of the documentation migration. The open-source pages move to lancedb/lancedb#4122 and are assembled from there.
Merge order: #352 → this → and lancedb/lancedb#4122 must land first, since CI assembles from that repository's
main.What moves and what stays
102 pages, the static assets, the generated snippets and the test suite they come from all move to
lancedb/lancedb/docs/web. This repository keeps what it still owns: the Geneva pages until Stage G replaces them, the generated dataset cards, the OpenAPI spec, and the Enterprise pages until A5 moves them to sophon.Navigation is the interesting part
It is authored once, in the root that owns the pages, so that root can be served on its own — a contributor runs
mint devindocs/webwith no second checkout. Everything this repository still holds is contributed as a fragment saying where each entry belongs: the chain of groups above it and the sibling it follows.Appending was not good enough. Sidebar order is what a reader navigates by, and appending dropped Geneva below Support and Datasets past Use Cases — a silent reordering of the whole site.
scripts/split_nav.pygenerates that fragment by walking the original navigation rather than by hand. That is why it contains six entries rather than ninety-seven: a container that moves wholesale is carried across intact instead of rebuilt from its children. A5 reuses it when the Enterprise pages move.Three things that had to match exactly
Each was caught by the harness, not by review:
openapiblock names a spec file this repository owns, and Mintlify refuses to build at all when it is missing. It is lifted out of the base navigation and restored by the fragment.docs.jsonis load-bearing. Mintlify hashes its CSS and JS bundles from those bytes, so movingnavigationrenamed every asset on every page — 179 differences from one reordered key.ensure_asciilikewise. The banner text carries an em-dash; escaping it differently changed the same bytes.CI
Now checks out
lancedb/lancedb@mainand assembles twice, comparing the two. The site no longer exists as a single tree anywhere, so comparing the assembly againstdocs/is no longer available — determinism is what the comparison can still establish, and a stale stored baseline is exactly what this harness was built to avoid.Verified
diff -rqclean against the pre-move sourcemint exportcomparison:VERDICT: EQUIVALENT, zero real differenceslancedb/lancedbbuilds and renders all 102 pages