Migrate the RAPIDS docs portal while preserving API hosting

.github/workflows/deploy.yaml

@@ -3,21 +3,31 @@ on:
   schedule:
     - cron: "0 9 * * *"
   workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "dry-run: build and log what would be published without uploading or flushing the CDN"
+        required: false
+        type: boolean
+        default: false
   push:
     branches:
       - main
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: false
 defaults:
   run:
     shell: bash
 permissions:
-  id-token: write
   contents: read
+env:
+  DRY_RUN: ${{ inputs.dry-run || false }}
+  RAPIDS_DOCS_BASE_URL: https://docs.nvidia.com/datascience/
+  UPLOAD: ${{ github.ref == 'refs/heads/main' }}
 jobs:
   build:
-    name: Build (and deploy)
+    name: Build and publish NVIDIA docs portal
+    if: ${{ github.repository == 'rapidsai/docs' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -32,26 +42,77 @@ jobs:
         run: uv sync --locked
       - name: Build and validate portal
         run: make check
-      - uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708 #v5.1.1
+      - name: Check out gha-tools
+        if: ${{ env.UPLOAD == 'true' }}
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: rapidsai/gha-tools
+          ref: main
+          path: gha-tools
+          persist-credentials: false
+          sparse-checkout: tools
+      - name: Add gha-tools to PATH
+        if: ${{ env.UPLOAD == 'true' }}
+        run: echo "${GITHUB_WORKSPACE}/gha-tools/tools" >> "${GITHUB_PATH}"
+      - name: Publish portal to NVIDIA docs
+        if: ${{ env.UPLOAD == 'true' }}
+        uses: rapidsai/shared-actions/publish-docs@82e2c50e4703a224de0bc8d0f6e5d12dcab68db7
+        with:
+          dry-run: ${{ env.DRY_RUN }}
+          source-path: _site
+          target-s3-key: datascience
+          target-s3-exclude: deployment/*
+          target-s3-bucket: ${{ secrets.NVIDIA_DOCS_S3_BUCKET }}
+          target-aws-access-key-id: ${{ secrets.NVIDIA_DOCS_AWS_ACCESS_KEY_ID }}
+          target-aws-secret-access-key: ${{ secrets.NVIDIA_DOCS_AWS_SECRET_ACCESS_KEY }}
+          target-aws-region: ${{ secrets.NVIDIA_DOCS_AWS_REGION }}
+          akamai-access-token: ${{ secrets.NVIDIA_DOCS_AKAMAI_ACCESS_TOKEN }}
+          akamai-client-secret: ${{ secrets.NVIDIA_DOCS_AKAMAI_CLIENT_SECRET }}
+          akamai-client-token: ${{ secrets.NVIDIA_DOCS_AKAMAI_CLIENT_TOKEN }}
+          akamai-emails-to-notify: ${{ secrets.NVIDIA_DOCS_AKAMAI_EMAILS_TO_NOTIFY }}
+          akamai-host: ${{ secrets.NVIDIA_DOCS_AKAMAI_HOST }}
+          akamai-request-name: rapidsai-docs-${{ github.run_id }}
+
+  compat:
+    name: Assemble and deploy docs.rapids.ai compatibility site
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --locked
+      - name: Build and validate portal
+        run: make check
+      - name: Configure source AWS credentials
+        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708 # v5.1.1
         with:
           role-to-assume: ${{ vars.AWS_ROLE_ARN }}
           aws-region: ${{ vars.AWS_REGION }}
-          role-duration-seconds: 7200 # 2h
-      - name: Assemble complete documentation site
+          role-duration-seconds: 7200
+      - name: Assemble and validate API documentation
         run: make assemble
-      - name: Deploy site
+      - name: Generate compatibility redirects
+        run: |
+          uv run python scripts/generate_redirect_site.py \
+            --output _site/_redirects
+      - name: Deploy compatibility site to docs.rapids.ai
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_API_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_DOCS_SITE_ID }}
-          # TODO: use official netlify-cli pkg after https://github.com/netlify/cli/issues/1809
-          # is resolved and deployed.
         run: | # zizmor: ignore[adhoc-packages]
           npm install --global --force @aschmidt8/netlify-cli
-
-          ARGS=""
-          if [ "$GITHUB_REF_NAME" = "main" ]; then
-            ARGS="--prod"
+          # Only main publishes production; other refs and dry runs produce a draft deploy.
+          ARGS=()
+          if [[ "${UPLOAD}" == "true" && "${DRY_RUN}" != "true" ]]; then
+            ARGS+=(--prod)
           fi
-          netlify deploy "$ARGS" \
-            --debug \
-            --dir=_site
+          netlify deploy "${ARGS[@]}" --debug --dir=_site

.github/workflows/pr.yaml

@@ -42,6 +42,8 @@ jobs:
     permissions:
       contents: read
       id-token: write
+    env:
+      RAPIDS_DOCS_BASE_URL: https://docs.nvidia.com/datascience/
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -55,11 +57,42 @@ jobs:
         run: uv sync --locked
       - name: Build and validate portal
         run: make check
-      - name: Configure AWS credentials
+      - name: Check out gha-tools
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: rapidsai/gha-tools
+          ref: main
+          path: gha-tools
+          persist-credentials: false
+          sparse-checkout: tools
+      - name: Add gha-tools to PATH
+        run: echo "${GITHUB_WORKSPACE}/gha-tools/tools" >> "${GITHUB_PATH}"
+      - name: Publish portal to NVIDIA docs
+        uses: rapidsai/shared-actions/publish-docs@82e2c50e4703a224de0bc8d0f6e5d12dcab68db7
+        with:
+          dry-run: true
+          source-path: _site
+          target-s3-key: datascience
+          target-s3-exclude: deployment/*
+          target-s3-bucket: ${{ secrets.NVIDIA_DOCS_S3_BUCKET }}
+          target-aws-access-key-id: ${{ secrets.NVIDIA_DOCS_AWS_ACCESS_KEY_ID }}
+          target-aws-secret-access-key: ${{ secrets.NVIDIA_DOCS_AWS_SECRET_ACCESS_KEY }}
+          target-aws-region: ${{ secrets.NVIDIA_DOCS_AWS_REGION }}
+          akamai-access-token: ${{ secrets.NVIDIA_DOCS_AKAMAI_ACCESS_TOKEN }}
+          akamai-client-secret: ${{ secrets.NVIDIA_DOCS_AKAMAI_CLIENT_SECRET }}
+          akamai-client-token: ${{ secrets.NVIDIA_DOCS_AKAMAI_CLIENT_TOKEN }}
+          akamai-emails-to-notify: ${{ secrets.NVIDIA_DOCS_AKAMAI_EMAILS_TO_NOTIFY }}
+          akamai-host: ${{ secrets.NVIDIA_DOCS_AKAMAI_HOST }}
+          akamai-request-name: rapidsai-docs-${{ github.run_id }}
+      - name: Configure source AWS credentials
         uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708 # v5.1.1
         with:
           role-to-assume: ${{ vars.AWS_ROLE_ARN }}
           aws-region: ${{ vars.AWS_REGION }}
           role-duration-seconds: 7200
-      - name: Assemble and validate complete documentation site
+      - name: Assemble and validate API documentation
         run: make assemble
+      - name: Generate compatibility redirects
+        run: |
+          uv run python scripts/generate_redirect_site.py \
+            --output _site/_redirects

404.md

@@ -6,12 +6,13 @@ orphan: true
 We could not find the page you were looking for.
 
 <script defer>
-  if (window.location.pathname.match(/^\/api.*/)) {
+  const portalBase = new URL("{{ site_baseurl }}");
+  if (window.location.pathname.startsWith(`${portalBase.pathname}api`)) {
     var redirectEl = document.createElement("p");
     redirectEl.innerHTML = "Redirecting you to the latest documentation in 5 seconds..."
     (document.querySelector("article") || document.body).appendChild(redirectEl);
     setTimeout(function() {
-      window.location.href = '/api/';
+      window.location.href = new URL("api/", portalBase).href;
     }, 5000);
   }
 </script>

README.md

@@ -1,7 +1,7 @@
 # NVIDIA RAPIDS Documentation
 
 This repository contains the source for the
-[NVIDIA RAPIDS documentation site](https://docs.rapids.ai/). The site is built
+[NVIDIA RAPIDS documentation site](https://docs.nvidia.com/datascience/). The site is built
 with Sphinx and the NVIDIA Sphinx theme.
 
 ## Build the site
@@ -16,31 +16,33 @@ make serve
 The rendered site is written to `_site`. The server uses port 8000 by default;
 override it with `PORT` (for example, `make serve PORT=8080`).
 
-## Build the full site
+Builds use `https://docs.nvidia.com/datascience/` as the default base URL.
+Set `RAPIDS_DOCS_BASE_URL` to override it.
 
-The complete docs site imports versioned API documentation and the deployment
-documentation from the private `rapidsai-docs` S3 bucket. Configure a read-only
-AWS profile named `rapids-docs`, then run:
+## Validation
+
+Run linting, tests, a strict Sphinx build, and rendered-site validation:
 
 ```shell
-AWS_PROFILE=rapids-docs make full
+make check
 ```
 
-This applies the RAPIDS library/version selectors to the imported documentation.
+Pull requests run validation and receive a Netlify preview.
 
-## Validation
+## Publishing
 
-```shell
-make check
-```
+Merges to `main` and the daily scheduled workflow publish the portal to
+`docs.nvidia.com/datascience/` using the shared `publish-docs` action.
+The independently published `datascience/deployment/` subtree is excluded from
+uploads and deletions. A manual run with the `dry-run` input builds everything
+and skips the upload, the CDN flush, and the production Netlify deploy.
 
-Run checks including linting, tests, and a local build.
+## Compatibility site
 
-Pull requests opened against `rapidsai/docs` are copied to a
-`pull-request/<number>` branch by the RAPIDS copy-PR bot. That branch runs the
-same validation and dry-runs assembly of the complete S3-backed documentation
-tree without deploying it. Netlify's repository integration separately creates
-a site preview. Merges to `main` deploy the production site.
+`docs.rapids.ai` continues to host unmigrated API documentation and redirect
+migrated content. The `compat` job in the [deploy workflow](.github/workflows/deploy.yaml)
+imports the remaining API docs from S3 and publishes them to Netlify, and runs
+only after the portal publish to `docs.nvidia.com` has succeeded.
 
 ## Repository layout
 

extensions/rapids_docs/api.py

@@ -3,23 +3,7 @@
 
 """Render the API documentation listings."""
 
-
-def _version_label(project: dict, version_name: str, releases: dict) -> str:
-    override = project.get("version-overrides", {}).get(version_name)
-    if override:
-        return str(override)
-    version_key = "ucxx_version" if "ucxx" in project["path"].lower() else "version"
-    return str(releases[version_name][version_key])
-
-
-def _documentation_url(project: dict, version_name: str, version: str) -> str:
-    first_docs_nvidia_com_release = project["first_docs_nvidia_com_release"]
-    if first_docs_nvidia_com_release and tuple(map(int, version.split("."))) >= tuple(
-        map(int, first_docs_nvidia_com_release.split("."))
-    ):
-        target_version = "latest" if version_name == "nightly" else version
-        return f"https://docs.nvidia.com/{project['path']}/{target_version}/"
-    return f"https://docs.rapids.ai/api/{project['path']}/{version_name}/"
+from .routes import _documentation_url, _version_label
 
 
 def _api_docs(data: dict, section: str) -> str:

extensions/rapids_docs/lifecycle.py

@@ -27,6 +27,8 @@ def _jinja_environment(app) -> Environment:
 
 def _context(app, docname: str = "index") -> dict:
     data = app.rapids_portal_data
+    config = getattr(app, "config", None)
+    site_baseurl = getattr(config, "html_baseurl", "https://docs.nvidia.com/datascience/")
     return {
         **data,
         "api_docs": lambda section: _api_docs(data, section),
@@ -36,6 +38,7 @@ def _context(app, docname: str = "index") -> dict:
         ),
         "platform_support_content": lambda: _platform_support(data),
         "previous_schedules": lambda: _previous_schedules(data),
+        "site_baseurl": site_baseurl.rstrip("/") + "/",
     }
 
 

extensions/rapids_docs/notices.py

@@ -13,6 +13,7 @@
 from bs4 import BeautifulSoup
 
 from .dates import _date, _long_date
+from .routes import _site_url
 
 _NOTICE_STATUS_COLORS = {"blue", "green", "purple", "red", "yellow"}
 
@@ -103,11 +104,12 @@ def _build_rss(app, exception) -> None:
     ElementTree.SubElement(
         channel, "description"
     ).text = "Notices communicate and document changes in RAPIDS for contributors, developers, users, and the community."
-    ElementTree.SubElement(channel, "link").text = "https://docs.rapids.ai/notices/"
+    base_url = app.config.html_baseurl
+    ElementTree.SubElement(channel, "link").text = _site_url(base_url, "/notices/")
     ElementTree.SubElement(
         channel,
         "{http://www.w3.org/2005/Atom}link",
-        href="https://docs.rapids.ai/notices/feed.xml",
+        href=_site_url(base_url, "/notices/feed.xml"),
         rel="self",
         type="application/rss+xml",
     )
@@ -129,7 +131,7 @@ def _build_rss(app, exception) -> None:
         ElementTree.SubElement(item, "description").text = html.unescape(description)
         published = notice.get("notice_updated") or notice["notice_created"]
         ElementTree.SubElement(item, "pubDate").text = _rss_date(published)
-        url = f"https://docs.rapids.ai/notices/{Path(notice['docname']).name}/"
+        url = _site_url(base_url, f"/notices/{Path(notice['docname']).name}/")
         ElementTree.SubElement(item, "link").text = url
         ElementTree.SubElement(item, "guid", isPermaLink="true").text = url
         for category in [*notice.get("tags", []), *notice.get("categories", [])]: