Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions .github/vercel-cli/pages-html-routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@
Usage: pages-html-routes.py OUTPUT_DIR

OUTPUT_DIR is a `.vercel/output` directory holding `static/` and a
`config.json` whose routes only set headers. The routes this script adds
follow those header routes.
`config.json` whose routes set headers, or redirect or rewrite a request
that the HTML routes must not see, such as the Explorer's host. The routes
this script adds follow them.
"""

import json
Expand Down Expand Up @@ -44,6 +45,12 @@ def html_routes(static: Path) -> list[dict]:
# Only reached when no file or directory matched.
redirect(r"^/(.+)/$", "/$1", 307),
{"src": r"^/(.+)$", "dest": "/$1.html", "check": True},
# An address that matches no file gets the build's 404 page, with a 404 status.
*(
[{"handle": "error"}, {"src": "^/.*$", "dest": "/404.html", "status": 404}]
if (static / "404.html").is_file()
else []
),
]


Expand All @@ -52,7 +59,7 @@ def main(output: Path) -> None:
config = json.loads(config_path.read_text())
routes = config.get("routes", [])
if any("handle" in route for route in routes):
sys.exit(f"{config_path}: routes must only set headers when HTML handling is added")
sys.exit(f"{config_path}: routes must not start a phase ('handle') when HTML handling is added")
config["routes"] = routes + html_routes(output / "static")
config_path.write_text(json.dumps(config, indent=2) + "\n")

Expand Down
18 changes: 15 additions & 3 deletions .github/workflows/docs-preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,10 @@ jobs:
'.github/workflows/docs-build.yml',
'.github/workflows/docs-preview.yml',
'.github/workflows/deploy-vercel.yml',
'.github/workflows/web-build.yml',
]);
eligible = files.some(file => [file.filename, file.previous_filename].some(
path => path && (path.startsWith('docs/') ||
path => path && (path.startsWith('docs/') || path.startsWith('vortex-web/') ||
path.startsWith('.github/vercel-cli/') || workflows.has(path)),
));
}
Expand All @@ -71,11 +72,22 @@ jobs:
cancel-in-progress: true
uses: ./.github/workflows/docs-build.yml

web:
name: Build Explorer preview
needs: changes
if: needs.changes.outputs.eligible == 'true'
permissions:
contents: read
concurrency:
group: docs-preview-web-${{ github.event.pull_request.number }}
cancel-in-progress: true
uses: ./.github/workflows/web-build.yml

# Each Vercel deployment has its own URL, so a stale build cannot replace
# a newer preview, and the PR needs no recheck before publishing.
publish:
name: Publish preview
needs: build
needs: [build, web]
permissions:
contents: read
deployments: write
Expand All @@ -85,6 +97,6 @@ jobs:
secrets: inherit
with:
environment: vercel-docs
artifact-ids: ${{ needs.build.outputs.artifact-id }}
artifact-ids: ${{ needs.build.outputs.artifact-id }},${{ needs.web.outputs.artifact-id }}
config: docs/vercel-output-config.json
pages-html-handling: true
11 changes: 9 additions & 2 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,16 @@ jobs:
build:
uses: ./.github/workflows/docs-build.yml

web:
name: Build Explorer
permissions:
contents: read
uses: ./.github/workflows/web-build.yml

# One Vercel project serves the docs and the Explorer.
deploy:
name: Deploy to Vercel
needs: build
needs: [build, web]
permissions:
contents: read
deployments: write
Expand All @@ -33,7 +40,7 @@ jobs:
secrets: inherit
with:
environment: vercel-docs
artifact-ids: ${{ needs.build.outputs.artifact-id }}
artifact-ids: ${{ needs.build.outputs.artifact-id }},${{ needs.web.outputs.artifact-id }}
config: docs/vercel-output-config.json
pages-html-handling: true
production: ${{ github.ref == 'refs/heads/develop' }}
56 changes: 56 additions & 0 deletions .github/workflows/web-build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright the Vortex contributors

name: Build Vortex Explorer

# The docs' Vercel project serves the Explorer: under /explorer/ on the docs
# and their previews, and at the root of explore.vortex.dev (see
# docs/vercel-output-config.json). So the artifact holds an explorer/
# directory, which the deploy merges into the docs build.
on:
workflow_call:
outputs:
artifact-id:
description: "Explorer artifact for this build"
value: ${{ jobs.build.outputs.artifact-id }}

jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 30
outputs:
artifact-id: ${{ steps.artifact.outputs.artifact-id }}
defaults:
run:
working-directory: vortex-web
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
ref: ${{ github.event.pull_request.head.sha || github.sha }}
persist-credentials: false
- uses: ./.github/actions/setup-rust
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
- name: Install wasm-pack
uses: taiki-e/install-action@1e29709c0ec63babbe8f266397a465f29a825f91 # v2
with:
tool: wasm-pack@0.15.0
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.3
# Vite runs on Node, and Bun runs its scripts with it.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: "24"
- run: bun install --frozen-lockfile
- run: bun run build
- name: Put the build under explorer/
run: mkdir site && mv dist site/explorer
- name: Upload build
id: artifact
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
with:
name: vortex-explorer-${{ github.run_attempt }}
path: vortex-web/site
if-no-files-found: error
retention-days: 7
54 changes: 2 additions & 52 deletions .github/workflows/web.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ defaults:
run:
working-directory: vortex-web

# The docs workflows build and deploy the Explorer (web-build.yml), because
# one Vercel project serves both.
jobs:
changes:
name: Detect Changes
Expand All @@ -38,8 +40,6 @@ jobs:
web:
- "vortex-web/**"
- ".github/workflows/web.yml"
- ".github/workflows/deploy-vercel.yml"
- ".github/vercel-cli/**"

check:
name: Check & Lint
Expand Down Expand Up @@ -69,53 +69,3 @@ jobs:
- run: bun run lint
- run: bun run typecheck
- run: bun run build-storybook

build:
name: Build
needs: [changes]
if: needs.changes.outputs.web == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- uses: ./.github/actions/setup-rust
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
- name: Install wasm-pack
uses: taiki-e/install-action@1e29709c0ec63babbe8f266397a465f29a825f91 # v2
with:
tool: wasm-pack@0.15.0
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
bun-version: 1.4.3
# Storybook and Vite run on Node, and Bun runs their scripts with it.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
with:
node-version: "24"
- run: bun install --frozen-lockfile
- run: bun run build
- name: Upload build artifact
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
with:
name: vortex-explorer
path: vortex-web/dist/

deploy:
name: Deploy to Vercel
needs: [build]
# Fork PRs get no secrets, so only pushes and same-repo PRs deploy.
if: >-
github.event_name == 'push' ||
github.event.pull_request.head.repo.full_name == github.repository
permissions:
contents: read
deployments: write
uses: ./.github/workflows/deploy-vercel.yml
# A called workflow only sees the secrets its caller passes, including
# the secrets of the environment the called job deploys to.
secrets: inherit
with:
environment: vercel-explorer
artifact-name: vortex-explorer
config: vortex-web/vercel-output-config.json
production: ${{ github.event_name == 'push' }}
8 changes: 5 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,8 +158,9 @@ Use `make -C docs help` to list focused targets, and finish documentation change

#### PR previews

PRs with branches in `vortex-data/vortex` get a docs preview when they change `docs/`, a docs
workflow, or the Vercel deploy files in `.github/vercel-cli/`. This includes draft PRs and PRs
PRs with branches in `vortex-data/vortex` get a docs preview when they change `docs/`,
`vortex-web/`, a docs or Explorer build workflow, or the Vercel deploy files in
`.github/vercel-cli/`. This includes draft PRs and PRs
targeting another feature branch. Fork PRs do not get hosted previews. Resolve merge conflicts
before building a preview.

Expand All @@ -168,7 +169,8 @@ source code. The label stays on the PR and enables previews for later pushes. Re
updates only if the PR no longer changes docs or a docs workflow.

Previews are hosted on Vercel. The `vercel-docs` deployment status links to the latest preview for
the PR, and the workflow summary records its URL. Each preview keeps its own URL. Previews build the
the PR, and the workflow summary records its URL. One Vercel project serves the docs and the
Explorer, so each preview also serves the Explorer at `/explorer/`. Each preview keeps its own URL. Previews build the
PR head commit. Eligibility uses the complete PR diff, so rebasing over upstream docs changes does
not enable a preview for an unrelated PR.

Expand Down
6 changes: 6 additions & 0 deletions LICENSES/LicenseRef-Third-Party.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Files marked LicenseRef-Third-Party are not licensed by the Vortex project.

The Apache-2.0 and CC-BY-4.0 grants that cover the rest of this repository do not apply to
them. Copyright in each file belongs to the holder named in its SPDX-FileCopyrightText entry
in REUSE.toml, and any trademarks it shows belong to their owners. For permission to reuse
one of these files, contact its holder.
16 changes: 16 additions & 0 deletions REUSE.toml
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,22 @@ precedence = "override"
SPDX-FileCopyrightText = "2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)"
SPDX-License-Identifier = "OFL-1.1"

# The Linux Foundation's logo, in the footer of the docs and the Explorer, belongs to the Linux
# Foundation.
[[annotations]]
path = ["docs/_static/lf_white.svg", "vortex-web/public/lf_white.svg"]
precedence = "override"
SPDX-FileCopyrightText = "The Linux Foundation"
SPDX-License-Identifier = "LicenseRef-Third-Party"

# three.js, which the docs serve for the 404's mark, because their CSP allows scripts from their
# own origin only. A copy of three@0.170.0's build/three.module.min.js.
[[annotations]]
path = "docs/_static/vortex-mark/three.module.min.js"
precedence = "override"
SPDX-FileCopyrightText = "2010-2024 Three.js Authors"
SPDX-License-Identifier = "MIT"

# BtrBlocks diagram is licensed under CC-BY-4.0.
[[annotations]]
path = "vortex-btrblocks/decision-tree.*"
Expand Down
7 changes: 5 additions & 2 deletions _typos.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
[default]
extend-ignore-identifiers-re = ["ffor", "FFOR", "FoR", "typ", "ratatui", "wht", "WHT"]
# metalness is a three.js material property, which the ASCII mark sets.
extend-ignore-identifiers-re = ["ffor", "FFOR", "FoR", "typ", "ratatui", "wht", "WHT", "metalness"]
# We support a few common special comments to tell the checker to ignore sections of code
extend-ignore-re = [
"(#|//)\\s*spellchecker:ignore-next-line\\n.*", # Ignore the next line
Expand All @@ -14,7 +15,9 @@ extend-ignore-re = [
extend-exclude = ["/vortex-bench/**", "/docs/references.bib", "benchmarks/**",
"vortex-sqllogictest/slt/**", "encodings/fsst/src/dfa/tests.rs",
"encodings/fsst/src/dfa/flat_contains.rs",
"scripts/measurement_id_golden.json", "scripts/ml64_reproducible.py"]
"scripts/measurement_id_golden.json", "scripts/ml64_reproducible.py",
# three.js, minified, which the docs serve for the 404's mark.
"docs/_static/vortex-mark/three.module.min.js"]

[type.py]
extend-ignore-identifiers-re = [
Expand Down
18 changes: 17 additions & 1 deletion docs/_ext/vortex_theme.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@
and fail the build if a copy of the system was edited by hand
2. Load only one CSS and no JS per page except search page
3. Rewrite TOC into detail/summary with regex so it loads without JS
4. Minify CSS
4. Make the 404 page's relative URLs root-relative, since it is served at any address
5. Minify CSS
"""

from __future__ import annotations
Expand Down Expand Up @@ -102,9 +103,24 @@ def _toc(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any],
context["vortex_globaltoc"] = html


# The 404 page is served at whatever address missed, so its relative links and assets would resolve
# against that address. Every relative URL in it becomes root-relative: links, assets, and the
# header's search form.
_RELATIVE_URL = re.compile(r'((?:href|src|action)=")(?![a-z][a-z0-9+.-]*:|/|#)')


def _root_relative_404(app: Sphinx, exception: Exception | None) -> None:
if exception is not None or app.builder.format != "html":
return
page = Path(app.outdir) / "404.html"
if page.exists():
page.write_text(_RELATIVE_URL.sub(r"\1/", page.read_text()))


def setup(app: Sphinx) -> dict[str, Any]:
_GEN_STATIC.mkdir(parents=True, exist_ok=True)
app.connect("builder-inited", _css)
app.connect("html-page-context", _filter_assets)
app.connect("html-page-context", _toc)
app.connect("build-finished", _root_relative_404)
return {"parallel_read_safe": True, "parallel_write_safe": True}
42 changes: 42 additions & 0 deletions docs/_static/lf_white.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading