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
44 changes: 44 additions & 0 deletions .github/workflows/Docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Deploy docs

on:
workflow_call:
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

jobs:
deploy:
if: >-
github.repository == 'vega/vl-convert' &&
(github.event_name != 'workflow_dispatch' || github.ref == 'refs/heads/main')
runs-on: ubuntu-latest
concurrency:
group: github-pages
cancel-in-progress: false
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Check out the latest generated site
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: gh-pages
persist-credentials: false
- name: Package the complete archive
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
with:
path: .
name: github-pages-${{ github.run_attempt }}
- name: Deploy GitHub Pages
id: deployment
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
with:
artifact_name: github-pages-${{ github.run_attempt }}
- name: Fetch the published site
env:
PAGE_URL: ${{ steps.deployment.outputs.page_url }}
run: |
curl --fail --silent --show-error --max-time 20 --retry 6 --retry-all-errors --retry-delay 5 "$PAGE_URL" > /dev/null
74 changes: 74 additions & 0 deletions .github/workflows/Release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -701,3 +701,77 @@ jobs:
GH_TOKEN: ${{ github.token }}
RELEASE_TAG: ${{ needs.validate.outputs.tag }}
run: gh release upload "$RELEASE_TAG" release-assets/* --clobber --repo "$GITHUB_REPOSITORY"

archive-docs:
name: Build and archive release documentation
if: github.event_name == 'release'
needs: [validate, upload-release-assets]
runs-on: macos-15-intel
concurrency:
group: github-pages
cancel-in-progress: false
permissions:
contents: write
env:
VERSION: ${{ needs.validate.outputs.version }}
SOURCE_SHA: ${{ needs.validate.outputs.source_ref }}
steps:
- name: Check out release source
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ needs.validate.outputs.source_ref }}
persist-credentials: false
- uses: prefix-dev/setup-pixi@a09b6247153796b190642a2b53fac4241043cf6f # v0.10.0
with:
pixi-version: v0.47.0
- uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
with:
prefix-key: v1-docs
cache-on-failure: true
- name: Build documentation with warnings as errors
run: pixi run docs-build-strict
- name: Serve documentation and fetch the homepage
run: |
pixi run python -m http.server 8000 --bind 127.0.0.1 --directory docs/build/html &
server_pid=$!
trap 'kill "$server_pid"' EXIT
curl --fail --silent --show-error --max-time 10 --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8000/ > /dev/null
- name: Load the archive or initialize its branch
env:
GH_TOKEN: ${{ github.token }}
run: |
gh auth setup-git
git init --initial-branch=gh-pages docs/build/archive
git -C docs/build/archive remote add origin "https://github.com/${GITHUB_REPOSITORY}.git"
existing=$(git -C docs/build/archive ls-remote --heads origin refs/heads/gh-pages)
if [[ -n "$existing" ]]; then
git -C docs/build/archive fetch --depth=1 origin gh-pages
git -C docs/build/archive checkout -B gh-pages FETCH_HEAD
fi
- name: Update the version directory and menu
run: |
pixi run python docs/tools/pages.py \
--build docs/build/html --site docs/build/archive \
--version "$VERSION" --source-sha "$SOURCE_SHA"
- name: Push the generated site
working-directory: docs/build/archive
env:
GH_TOKEN: ${{ github.token }}
run: |
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git add .
if ! git diff --cached --quiet; then
git commit -m "docs: publish $VERSION"
git push origin HEAD:refs/heads/gh-pages
fi

deploy-docs:
name: Deploy release documentation
needs: archive-docs
permissions:
contents: read
pages: write
id-token: write
# GITHUB_TOKEN pushes do not trigger workflows, so call deployment explicitly.
uses: ./.github/workflows/Docs.yml
6 changes: 6 additions & 0 deletions DEVELOP.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,12 @@ Configure trusted publishing with the `vega/vl-convert` repository, `.github/wor
- The `vl-convert-python` project on PyPI.
- The `vl-convert`, `vl-convert-canvas2d`, `vl-convert-canvas2d-deno`, `vl-convert-google-fonts`, `vl-convert-rs`, and `vl-convert-server` crates on crates.io.

# Release documentation hosting

The docs workflow runs after package and release asset publication succeeds. See
[documentation publication and recovery](docs/README.md#publish-release-documentation)
for the archive layout, menu policy, and docs-only retries.

# Rust API documentation

Build the supported Rust API with missing documentation and broken links treated as errors:
Expand Down
27 changes: 27 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,3 +79,30 @@ pixi run ruff check docs/tools docs/source/_ext
Use `pixi run docs-serve` for a live preview. Its pre-build commands regenerate
the interface pages, setup files, and server request bodies after a source
change.

## Publish release documentation

After package and release asset publication succeeds, the `Release` workflow
builds docs from the release checkout, updates `gh-pages/<VERSION>/`, and
deploys the site at `https://vega.github.io/vl-convert/`.

The root points to the newest stable release, or a preview link before the
first stable release. The dropdown lists the latest patch per stable minor
series and the newest RC newer than stable. Older versions retain their URLs
even when removed from the menu.

### Retry or correct the site

For build or archive failures, rerun the failed jobs in the original Release
run. Successful package-publishing jobs do not repeat.

To deploy the current `gh-pages` contents without rebuilding docs or publishing
packages:

```bash
gh workflow run Docs.yml --ref main
```

For a small correction, edit the generated files on `gh-pages`, push, and run
that command. Also fix the source docs for future releases. Rebuilding a
version overwrites its direct HTML edits.
10 changes: 0 additions & 10 deletions docs/source/_static/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -128,16 +128,6 @@ html {
font-weight: 400;
}

.release-version {
display: inline-block;
padding: 0.2rem 0.5rem;
border: 1px solid var(--pst-color-border);
border-radius: 0.375rem;
color: var(--pst-color-text-base);
font-size: 0.875rem;
white-space: nowrap;
}

.rendered-chart {
display: block;
max-width: 100%;
Expand Down
1 change: 0 additions & 1 deletion docs/source/_templates/release-version.html

This file was deleted.

4 changes: 4 additions & 0 deletions docs/source/_templates/version-menu.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{# Keep the Cargo version visible when this release is absent from the menu. #}
{% filter replace("Choose version", "v" ~ release) %}
{% include "components/version-switcher.html" %}
{% endfilter %}
13 changes: 12 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
from __future__ import annotations

import os
import sys
import tomllib
from html import escape
Expand Down Expand Up @@ -33,6 +34,10 @@
html_theme = "pydata_sphinx_theme"
templates_path = ["_templates"]
html_title = "VlConvert"
DOCS_SITE_URL = os.environ.get(
"VLC_DOCS_SITE_URL", "https://vega.github.io/vl-convert"
).rstrip("/")
html_baseurl = f"{DOCS_SITE_URL}/{release}/"
# Logo assets live in the top-level logo/ directory. Sphinx and the theme copy
# them into the output _static/ directory at build time.
LOGO_DIR = ROOT / "logo"
Expand All @@ -43,7 +48,13 @@
html_theme_options = {
"github_url": "https://github.com/vega/vl-convert",
"navbar_align": "left",
"navbar_end": ["release-version", "theme-switcher", "navbar-icon-links"],
"navbar_end": ["version-menu", "theme-switcher", "navbar-icon-links"],
"switcher": {
"json_url": f"{DOCS_SITE_URL}/versions.json",
"version_match": release,
},
# Builds must not depend on a published manifest, including the first release.
"check_switcher": False,
"header_links_before_dropdown": 4,
"show_toc_level": 2,
"logo": {
Expand Down
131 changes: 131 additions & 0 deletions docs/tools/pages.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
"""Assemble the versioned GitHub Pages archive from a documentation build."""

from __future__ import annotations

import argparse
import json
import re
import shutil
from pathlib import Path

from packaging.version import Version

SITE_URL = "https://vega.github.io/vl-convert"


def version_key(value: str) -> Version:
"""Validate the release directory format and return its sortable version."""
if not re.fullmatch(r"\d+\.\d+\.\d+(?:-rc\d+)?", value):
raise ValueError(f"Unsupported documentation version: {value}")
return Version(value)


def archive(args):
"""Replace one version and regenerate the shared menu without deleting older versions."""
# Validate the destination name and build contents before replacing files.
version_key(args.version)
if not re.fullmatch(r"[0-9a-f]{40}", args.source_sha):
raise ValueError("Expected a full source commit SHA")
source, site = args.build.resolve(), args.site.resolve()
if not (source / "index.html").is_file():
raise ValueError("The version build has no index.html")
for path in source.rglob("*"):
if path.is_symlink() or path.name == ".git":
raise ValueError(f"Unexpected link or Git metadata in build: {path}")

# A retry replaces only this version and records the source used to build it.
target = site / args.version
if target.is_symlink():
raise ValueError("The version destination must not be a symlink")
if target.exists():
shutil.rmtree(target)
shutil.copytree(source, target)
(target / "release.json").write_text(
json.dumps(
{
"version": args.version,
"source_sha": args.source_sha,
},
indent=2,
)
+ "\n",
encoding="utf-8",
)

# Derive the menu from archived builds, not from all published releases.
versions = []
for metadata in site.glob("*/release.json"):
version = json.loads(metadata.read_text(encoding="utf-8"))["version"]
version_key(version)
if metadata.parent.name != version:
raise ValueError(f"Version metadata does not match directory: {metadata}")
versions.append(version)
versions.sort(key=version_key, reverse=True)

# Keep the newest stable patch per minor series in the menu.
stable = [v for v in versions if not version_key(v).is_prerelease]
latest = stable[0] if stable else None
series = set()
selected = []
for version in stable:
key = version_key(version).release[:2]
if key not in series:
selected.append(version)
series.add(key)

# Show only the newest RC, and only while it is newer than stable.
previews = [
v
for v in versions
if version_key(v).is_prerelease
and (latest is None or version_key(v) > version_key(latest))
]
if previews:
selected.insert(1 if latest else 0, previews[0])

# Every archived page reads this shared theme-switcher manifest.
url = args.url.rstrip("/")
menu = []
for version in selected:
entry = {"version": version, "url": f"{url}/{version}/", "name": version}
if version == latest:
entry.update(name=f"{version} (stable)", preferred=True)
elif version_key(version).is_prerelease:
entry["name"] += " (preview)"
menu.append(entry)
(site / "versions.json").write_text(
json.dumps(menu, indent=2) + "\n", encoding="utf-8"
)

# Prereleases never replace the stable redirect at the site root.
if latest:
body = (
f'<meta http-equiv="refresh" content="0; url={latest}/">'
f'<p><a href="{latest}/">VlConvert {latest} documentation</a></p>'
)
else:
body = (
f"<h1>VlConvert preview documentation</h1>"
f"<p>No stable documentation has been published yet. "
f'<a href="{previews[0]}/">Read the {previews[0]} preview</a>.</p>'
)
(site / "index.html").write_text(
'<!doctype html><html lang="en"><meta charset="utf-8">'
'<meta name="viewport" content="width=device-width, initial-scale=1">'
"<title>VlConvert documentation</title>" + body + "</html>\n",
encoding="utf-8",
)
(site / ".nojekyll").touch()


if __name__ == "__main__":
# Accept the build and release metadata supplied by the release workflow.
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--build", type=Path, required=True)
parser.add_argument("--site", type=Path, required=True)
parser.add_argument("--version", required=True)
parser.add_argument("--source-sha", required=True)
parser.add_argument("--url", default=SITE_URL)

# Update one archived version and the shared navigation files.
archive(parser.parse_args())
Loading