Skip to content

feat: assemble the open-source pages from lancedb/lancedb - #355

Open
jackye1995 wants to merge 2 commits into
jack/exclude-dotfilesfrom
jack/a3-move
Open

feat: assemble the open-source pages from lancedb/lancedb#355
jackye1995 wants to merge 2 commits into
jack/exclude-dotfilesfrom
jack/a3-move

Conversation

@jackye1995

Copy link
Copy Markdown
Contributor

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 dev in docs/web with 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.py generates 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:

  • The openapi block 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.
  • 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 — 179 differences from one reordered key.
  • ensure_ascii likewise. The banner text carries an em-dash; escaping it differently changed the same bytes.

CI

Now checks out lancedb/lancedb@main and assembles twice, comparing the two. The site no longer exists as a single tree anywhere, so comparing the assembly against docs/ 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

  • assembled tree byte-identical to the one it replaces — diff -rq clean against the pre-move source
  • two consecutive assemblies identical
  • full mint export comparison: VERDICT: EQUIVALENT, zero real differences
  • link check clean
  • the standalone site in lancedb/lancedb builds and renders all 102 pages

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.
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.

1 participant