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

.github/workflows/assemble.yml

@@ -35,6 +35,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      # The open-source pages live in lancedb/lancedb and are assembled from
+      # there. Pinned to main: this repository publishes what that repository
+      # has merged, not what is in flight.
+      - name: Check out the open-source documentation
+        uses: actions/checkout@v4
+        with:
+          repository: lancedb/lancedb
+          ref: main
+          path: lancedb
+
       - uses: actions/setup-node@v4
         with:
           node-version: 22
@@ -49,9 +59,13 @@ jobs:
       # have drifted the site would document something that was never released.
       - name: Check the OpenAPI spec matches its release
         run: make check-spec
+        env:
+          LANCEDB_DOCS_ROOT: lancedb/docs/web
 
       - name: Assemble
         run: make assemble
+        env:
+          LANCEDB_DOCS_ROOT: lancedb/docs/web
 
       - name: Check links in the assembled tree
         working-directory: build/site
@@ -65,8 +79,17 @@ jobs:
         working-directory: build/site
         run: mint export --output "$RUNNER_TEMP/assembled.zip"
 
-      - name: Export the source tree
-        working-directory: docs
+      # Nothing to compare against directly any more: the site no longer exists
+      # as one tree anywhere. Assembling twice proves the pipeline is
+      # deterministic, which is what the comparison can still establish.
+      - name: Assemble again
+        run: make assemble
+        env:
+          LANCEDB_DOCS_ROOT: lancedb/docs/web
+          ASSEMBLE_OUTPUT: build/site-again
+
+      - name: Export the second assembly
+        working-directory: build/site-again
         run: mint export --output "$RUNNER_TEMP/direct.zip"
 
       - name: Compare

.gitignore

@@ -28,3 +28,6 @@ scratch
 # Assembled output — generated by scripts/assemble.py, published to the
 # `assembled` branch by CI rather than committed here.
 /build/
+
+# Second assembly, used by CI to prove the pipeline is deterministic.
+/build/

assemble.yaml

@@ -1,35 +1,29 @@
 # Assembler configuration.
 #
-# The site is built from one or more content roots rather than published
-# directly from this repository. Today there is a single root — this repo's own
-# `docs/` — and the assembled output is byte-identical to it. Later phases add
-# roots without changing the program:
+# The published site is built from several content roots. The first `reference`
+# root owns the navigation and ships a complete `docs.json`, so it can also be
+# served on its own with `mint dev` — that is how a contributor previews the
+# open-source documentation without this repository at all. Every other root
+# contributes a `docs.nav.json` fragment, whose tabs are merged by name.
 #
-#   A3  the open-source pages move to lancedb/lancedb, added here as a second
-#       `reference` root
-#   A5  the Enterprise overlays land in sophon, added as an `overlay` root whose
-#       fragments merge onto reference anchors
-#
-# Adding a root is an edit to this file, not to scripts/assemble.py. That is the
-# point of keeping it declarative.
+# A5 adds sophon as an `overlay` root, whose Enterprise fragments merge onto
+# reference anchors. That is a config edit, not a code change.
 
-output: build/site
+output: ${ASSEMBLE_OUTPUT:-build/site}
 
 roots:
-  - name: oss
+  # Open-source pages, and the navigation for the whole site. Override the path
+  # with LANCEDB_DOCS_ROOT when the checkout is somewhere else; CI sets it.
+  - name: lancedb
+    path: ${LANCEDB_DOCS_ROOT:-../lancedb/docs/web}
+    role: reference
+
+  # What this repository still owns: the Geneva pages until Stage G replaces
+  # them, the generated dataset cards, and the OpenAPI spec.
+  - name: build
     path: docs
     role: reference
 
-# Generated inputs the assembler owns rather than trusting a bot to commit.
-#
-# The REST reference is generated from the Lance Namespace OpenAPI spec. It is
-# tracked at a *release tag*, not a commit: the site should document something
-# that was released. `make sync-spec` writes the released spec into the tree and
-# CI fails if the two have drifted, so the pin cannot rot silently.
-#
-# v0.12.0 is the first release carrying the fix for the broken request examples
-# (lance-format/lance-namespace#362). Anything older renders "A valid request
-# URL is required to generate request examples" on most endpoint pages.
 openapi:
   repo: lance-format/lance-namespace
   release: v0.12.0