diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index d049037831a..4c86a5e063a 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,24 +1,13 @@ -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/jekyll +// For format details, see https://aka.ms/devcontainer.json. { - "name": "Jekyll", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/jekyll:2-bullseye", - "features": { - } - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Uncomment the next line to run commands after the container is created. - // "postCreateCommand": "jekyll --version" - - // Configure tool-specific properties. - // "customizations": {}, - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" + "name": "RAPIDS Docs", + "image": "mcr.microsoft.com/devcontainers/python:3.14-bookworm", + "forwardPorts": [8000], + "portsAttributes": { + "8000": { + "label": "RAPIDS Docs", + "onAutoForward": "openPreview" + } + }, + "postCreateCommand": "pipx install uv && uv sync --locked" } diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 771d76cc86b..5ae8eeadeef 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -24,21 +24,21 @@ jobs: with: fetch-depth: 0 persist-credentials: false - # this step uses the `.ruby-version` file - - uses: ruby/setup-ruby@6aaa311d81eba98ae12eaffbcb63296ace0efcde # v1.307.0 - - name: Build Jekyll Site - run: | - bundle install - bundle exec jekyll build + - 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 - 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: Fetch doc files from S3 - run: ci/download_from_s3.sh - - name: Post-process docs - run: ci/post-process.sh + - name: Assemble complete documentation site + run: make assemble - name: Deploy site env: NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_API_TOKEN }} diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml index 6cde6c075a7..61b61c21ff2 100644 --- a/.github/workflows/pr.yaml +++ b/.github/workflows/pr.yaml @@ -20,3 +20,30 @@ jobs: with: persist-credentials: false - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1 + + docs: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - name: Checkout + 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 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 + run: make assemble diff --git a/.gitignore b/.gitignore index d2e9d00015e..3ffa7835d2d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,7 @@ -_site/ -_sass/ -.sass-cache/ --P/ -.vscode -lib_map.json -.DS_Store -files-to-customize.txt -.jekyll-cache -.jekyll-metadata -.netlify +/.ruff_cache/ +/.venv/ +/_site/ +/files-to-customize.txt +/ci/customization/lib_map.json __pycache__/ -node_modules -rapids-docs-env/ +*.pyc diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 404742e42c5..da79750707c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,4 +1,4 @@ -# Copyright (c) 2024-2025, NVIDIA CORPORATION. +# Copyright (c) 2024-2026, NVIDIA CORPORATION. ci: autofix_commit_msg: "[pre-commit.ci] auto code formatting" diff --git a/.python-version b/.python-version new file mode 100644 index 00000000000..6324d401a06 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.14 diff --git a/.ruby-version b/.ruby-version deleted file mode 100644 index 15a27998172..00000000000 --- a/.ruby-version +++ /dev/null @@ -1 +0,0 @@ -3.3.0 diff --git a/404.md b/404.md index 1b788d5795e..236231eb33b 100644 --- a/404.md +++ b/404.md @@ -1,9 +1,6 @@ --- -layout: default -permalink: /404.html -nav_exclude: true +orphan: true --- - # Page Not Found We could not find the page you were looking for. @@ -12,9 +9,9 @@ We could not find the page you were looking for. if (window.location.pathname.match(/^\/api.*/)) { var redirectEl = document.createElement("p"); redirectEl.innerHTML = "Redirecting you to the latest documentation in 5 seconds..." - document.getElementById("main-content").appendChild(redirectEl); + (document.querySelector("article") || document.body).appendChild(redirectEl); setTimeout(function() { - window.location.href = '/api'; + window.location.href = '/api/'; }, 5000); } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 424c77625f5..86073808732 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,148 +2,91 @@ ## Environment setup -- Install Ruby -- Install Bundler -- Checkout repo -- Run `bundle install` in checked out repo - -## Development - -```sh -bundle exec jekyll serve -``` - -### Dev Containers - -If you're using [VSCode](https://code.visualstudio.com/) you can use the jekyll Dev Container. - -- This project contains a devcontainer config: - - If prompted with "Folder contains a Dev Container configuration file." select "Reopen in Container" - - Alternatively select "Dev Containers: Reopen in Container" from the command palette -- Run `bundle exec jekyll serve` - -### Local Docker development - -Alternatively, you can use the [jekyll-docker](https://github.com/envygeeks/jekyll-docker) container to build and serve the `docs` site locally: - -```sh -docker run --rm \ - --volume="$PWD:/srv/jekyll" \ - --publish [::1]:4000:4000 \ - jekyll/jekyll \ - bash -c 'rm -rf ./_site && jekyll serve' -``` - -### Local macOS development - -Upgrade to a new-enough ruby and install `jekyll`, like following https://jekyllrb.com/docs/installation/macos/ - -```shell -# (one-time) get ruby env-management stuff -brew install chruby ruby-install - -# (one time) update to newer ruby -ruby-install ruby 3.4.1 - -source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh -source $(brew --prefix)/opt/chruby/share/chruby/auto.sh -chruby ruby-3.4.1 -ruby -v - -# (one time) install Bundler -gem install bundler - -# install everything else the project needs -bundle install -``` - -Build the site (this populates the `_site/` folder) +Install [uv](https://docs.astral.sh/uv/), check out the repository, and install +the locked development environment: ```shell -bundle exec jekyll build --verbose +uv sync --locked ``` -At this point, the API documentation will not be populated. - -To test those and the post-processing that happens on them, get read-only AWS credentials for the relevant resources -and put them in a profile called `[rapids-docs]` in your AWS CLI configuration. +Alternatively, open the repository in its development container. The container +installs uv and the locked environment automatically. -```shell -export AWS_DEFAULT_PROFILE="rapids-docs" -ci/download_from_s3.sh -``` - -At this point, the site is now built and the API documentation has been downloaded. -Next, some post-processing needs to be done to point links like `/stable` (including those in drop-down selectors) -to the appropriate documentation files. +## Development -Those steps include a `pip install`, so create and active a Python virtual environment first. +Build the portal and serve the rendered site: ```shell -python -m venv rapids-docs-env -source ./rapids-docs-env/bin/activate +make html +make serve ``` -Then run the post-processing. +The server uses port 8000 by default. Pass a different port when needed: ```shell -ci/post-process.sh +make serve PORT=8080 ``` -At this point, you should be able to view the site locally with a pretty similar experience to what's hosted in deployments. - -`jekyll serve` cleans and re-generates the `_site/` folder, but it also does some other bundling and packaging that's needed for links and formatting -to work correctly. - -First, back up the `api/` directory: +Run site validation before submitting a change: ```shell -BACKUP_DIR=$(mktemp -d) -cp -avR ./_site/api "${BACKUP_DIR}" +make check ``` -Then serve the site. +This runs formatting and lint checks, unit tests, a strict Sphinx build, and +route and rendered-content validation. -```shell -bundle exec jekyll serve -``` +## Full documentation assembly -Once it's up, copy all the `api/` files back in. +The portal-only build does not include the versioned API documentation or the +deployment documentation. To test the complete site and its post-processing, +obtain read-only AWS credentials for the documentation bucket and configure an +AWS CLI profile named `rapids-docs`. Then run: ```shell -cp -avR "${BACKUP_DIR}/api" _site +AWS_PROFILE=rapids-docs make full ``` -`jekyll serve` should automatically pick up the changes. - -In a browser, navigate to the URL shown in the `jekyll serve` output (probably something like `http://127.0.0.1:4000/`) to see the rendered docs. - -If the hot reloading in `jekyll serve` again deletes all the files in `api/`, just copy them in again. +This builds the Sphinx portal into `_site`, downloads the imported +documentation, creates the stable, latest, nightly, and legacy aliases, adds +the RAPIDS library and version selectors, and validates the assembled site. +Serve the result without rebuilding it with: ```shell -cp -avR "${BACKUP_DIR}/api" _site +make serve ``` ## PR submissions -Once you have code changes, submit a PR to the docs site. Netlify will generate -a preview of your changes and the team will review. +Submit changes as a pull request to `rapidsai/docs`. The RAPIDS copy-PR bot +copies the pull request head to a `pull-request/` branch in the upstream +repository. CI validates that branch and dry-runs assembly of the complete +S3-backed documentation site without deploying it. Netlify's repository +integration separately creates a portal-only preview for review. ## Developer Certificate of Origin -All contributions to this project must be accompanied by a sign-off indicating that the contribution is made pursuant to the Developer Certificate of Origin (DCO). This is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project. +All contributions to this project must be accompanied by a sign-off indicating +that the contribution is made pursuant to the Developer Certificate of Origin +(DCO). This is a lightweight way for contributors to certify that they wrote +or otherwise have the right to submit the code they are contributing to the +project. -The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution. To certify your adherence to the DCO, you must sign off on your commits. This is done by adding a `Signed-off-by` line to your commit messages: +The DCO is a simple statement that you, as a contributor, have the legal right +to make the contribution. To certify your adherence to the DCO, you must sign +off on your commits. This is done by adding a `Signed-off-by` line to your +commit messages: -``` +```text Signed-off-by: Random J Developer ``` You can do this automatically with `git commit -s`. -Here is the full text of the DCO, which you can also find at : +Here is the full text of the DCO, which you can also find at +: -``` +```text Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: diff --git a/Gemfile b/Gemfile deleted file mode 100644 index 8197051a907..00000000000 --- a/Gemfile +++ /dev/null @@ -1,5 +0,0 @@ -source 'https://rubygems.org' -gem 'github-pages', group: :jekyll_plugins -gem "just-the-docs", "= 0.3.3" - -gem "webrick", "~> 1.8" diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index b60165eb87f..00000000000 --- a/Gemfile.lock +++ /dev/null @@ -1,292 +0,0 @@ -GEM - remote: https://rubygems.org/ - specs: - activesupport (7.2.3.1) - base64 - benchmark (>= 0.3) - bigdecimal - concurrent-ruby (~> 1.0, >= 1.3.1) - connection_pool (>= 2.2.5) - drb - i18n (>= 1.6, < 2) - logger (>= 1.4.2) - minitest (>= 5.1, < 6) - securerandom (>= 0.3) - tzinfo (~> 2.0, >= 2.0.5) - addressable (2.9.0) - public_suffix (>= 2.0.2, < 8.0) - base64 (0.3.0) - benchmark (0.5.0) - bigdecimal (4.0.1) - coffee-script (2.4.1) - coffee-script-source - execjs - coffee-script-source (1.12.2) - colorator (1.1.0) - commonmarker (0.23.10) - concurrent-ruby (1.3.7) - connection_pool (3.0.2) - csv (3.3.0) - dnsruby (1.72.2) - simpleidn (~> 0.2.1) - drb (2.2.3) - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - ethon (0.16.0) - ffi (>= 1.15.0) - eventmachine (1.2.7) - execjs (2.9.1) - faraday (2.14.3) - faraday-net_http (>= 2.0, < 3.5) - json - logger - faraday-net_http (3.4.4) - net-http (~> 0.5) - ffi (1.17.0) - ffi (1.17.0-x86_64-linux-gnu) - forwardable-extended (2.6.0) - gemoji (4.1.0) - github-pages (232) - github-pages-health-check (= 1.18.2) - jekyll (= 3.10.0) - jekyll-avatar (= 0.8.0) - jekyll-coffeescript (= 1.2.2) - jekyll-commonmark-ghpages (= 0.5.1) - jekyll-default-layout (= 0.1.5) - jekyll-feed (= 0.17.0) - jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.16.1) - jekyll-include-cache (= 0.2.1) - jekyll-mentions (= 1.6.0) - jekyll-optional-front-matter (= 0.3.2) - jekyll-paginate (= 1.1.0) - jekyll-readme-index (= 0.3.0) - jekyll-redirect-from (= 0.16.0) - jekyll-relative-links (= 0.6.1) - jekyll-remote-theme (= 0.4.3) - jekyll-sass-converter (= 1.5.2) - jekyll-seo-tag (= 2.8.0) - jekyll-sitemap (= 1.4.0) - jekyll-swiss (= 1.0.0) - jekyll-theme-architect (= 0.2.0) - jekyll-theme-cayman (= 0.2.0) - jekyll-theme-dinky (= 0.2.0) - jekyll-theme-hacker (= 0.2.0) - jekyll-theme-leap-day (= 0.2.0) - jekyll-theme-merlot (= 0.2.0) - jekyll-theme-midnight (= 0.2.0) - jekyll-theme-minimal (= 0.2.0) - jekyll-theme-modernist (= 0.2.0) - jekyll-theme-primer (= 0.6.0) - jekyll-theme-slate (= 0.2.0) - jekyll-theme-tactile (= 0.2.0) - jekyll-theme-time-machine (= 0.2.0) - jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.13.0) - kramdown (= 2.4.0) - kramdown-parser-gfm (= 1.1.0) - liquid (= 4.0.4) - mercenary (~> 0.3) - minima (= 2.5.1) - nokogiri (>= 1.16.2, < 2.0) - rouge (= 3.30.0) - terminal-table (~> 1.4) - webrick (~> 1.8) - github-pages-health-check (1.18.2) - addressable (~> 2.3) - dnsruby (~> 1.60) - octokit (>= 4, < 8) - public_suffix (>= 3.0, < 6.0) - typhoeus (~> 1.3) - html-pipeline (2.14.3) - activesupport (>= 2) - nokogiri (>= 1.4) - http_parser.rb (0.8.0) - i18n (1.14.8) - concurrent-ruby (~> 1.0) - jekyll (3.10.0) - addressable (~> 2.4) - colorator (~> 1.0) - csv (~> 3.0) - em-websocket (~> 0.5) - i18n (>= 0.7, < 2) - jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 2.0) - kramdown (>= 1.17, < 3) - liquid (~> 4.0) - mercenary (~> 0.3.3) - pathutil (~> 0.9) - rouge (>= 1.7, < 4) - safe_yaml (~> 1.0) - webrick (>= 1.0) - jekyll-avatar (0.8.0) - jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.2.2) - coffee-script (~> 2.2) - coffee-script-source (~> 1.12) - jekyll-commonmark (1.4.0) - commonmarker (~> 0.22) - jekyll-commonmark-ghpages (0.5.1) - commonmarker (>= 0.23.7, < 1.1.0) - jekyll (>= 3.9, < 4.0) - jekyll-commonmark (~> 1.4.0) - rouge (>= 2.0, < 5.0) - jekyll-default-layout (0.1.5) - jekyll (>= 3.0, < 5.0) - jekyll-feed (0.17.0) - jekyll (>= 3.7, < 5.0) - jekyll-gist (1.5.0) - octokit (~> 4.2) - jekyll-github-metadata (2.16.1) - jekyll (>= 3.4, < 5.0) - octokit (>= 4, < 7, != 4.4.0) - jekyll-include-cache (0.2.1) - jekyll (>= 3.7, < 5.0) - jekyll-mentions (1.6.0) - html-pipeline (~> 2.3) - jekyll (>= 3.7, < 5.0) - jekyll-optional-front-matter (0.3.2) - jekyll (>= 3.0, < 5.0) - jekyll-paginate (1.1.0) - jekyll-readme-index (0.3.0) - jekyll (>= 3.0, < 5.0) - jekyll-redirect-from (0.16.0) - jekyll (>= 3.3, < 5.0) - jekyll-relative-links (0.6.1) - jekyll (>= 3.3, < 5.0) - jekyll-remote-theme (0.4.3) - addressable (~> 2.0) - jekyll (>= 3.5, < 5.0) - jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) - rubyzip (>= 1.3.0, < 3.0) - jekyll-sass-converter (1.5.2) - sass (~> 3.4) - jekyll-seo-tag (2.8.0) - jekyll (>= 3.8, < 5.0) - jekyll-sitemap (1.4.0) - jekyll (>= 3.7, < 5.0) - jekyll-swiss (1.0.0) - jekyll-theme-architect (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-cayman (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-dinky (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-hacker (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-leap-day (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-merlot (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-midnight (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-minimal (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-modernist (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-primer (0.6.0) - jekyll (> 3.5, < 5.0) - jekyll-github-metadata (~> 2.9) - jekyll-seo-tag (~> 2.0) - jekyll-theme-slate (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-tactile (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-theme-time-machine (0.2.0) - jekyll (> 3.5, < 5.0) - jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.3) - jekyll (>= 3.3, < 5.0) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.13.0) - gemoji (>= 3, < 5) - html-pipeline (~> 2.2) - jekyll (>= 3.0, < 5.0) - json (2.20.0) - just-the-docs (0.3.3) - jekyll (>= 3.8.5) - jekyll-seo-tag (~> 2.0) - rake (>= 12.3.1, < 13.1.0) - kramdown (2.4.0) - rexml - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - liquid (4.0.4) - listen (3.9.0) - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - logger (1.7.0) - mercenary (0.3.6) - minima (2.5.1) - jekyll (>= 3.5, < 5.0) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) - minitest (5.27.0) - net-http (0.9.1) - uri (>= 0.11.1) - nokogiri (1.19.4-aarch64-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.4-arm64-darwin) - racc (~> 1.4) - nokogiri (1.19.4-x86_64-linux-gnu) - racc (~> 1.4) - octokit (4.25.1) - faraday (>= 1, < 3) - sawyer (~> 0.9) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - public_suffix (5.1.1) - racc (1.8.1) - rake (13.0.6) - rb-fsevent (0.11.2) - rb-inotify (0.11.1) - ffi (~> 1.0) - rexml (3.4.2) - rouge (3.30.0) - rubyzip (2.3.2) - safe_yaml (1.0.5) - sass (3.7.4) - sass-listen (~> 4.0.0) - sass-listen (4.0.0) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - sawyer (0.9.2) - addressable (>= 2.3.5) - faraday (>= 0.17.3, < 3) - securerandom (0.4.1) - simpleidn (0.2.3) - terminal-table (1.8.0) - unicode-display_width (~> 1.1, >= 1.1.1) - typhoeus (1.4.1) - ethon (>= 0.9.0) - tzinfo (2.0.6) - concurrent-ruby (~> 1.0) - unicode-display_width (1.8.0) - uri (1.1.1) - webrick (1.8.2) - -PLATFORMS - aarch64-linux - arm64-darwin-24 - x86_64-linux - -DEPENDENCIES - github-pages - just-the-docs (= 0.3.3) - webrick (~> 1.8) - -BUNDLED WITH - 2.5.16 diff --git a/Makefile b/Makefile new file mode 100644 index 00000000000..dc2c053f77d --- /dev/null +++ b/Makefile @@ -0,0 +1,33 @@ +UV ?= uv +PORT ?= 8000 +AWS_PROFILE ?= + +.PHONY: assemble check clean full html lint serve test validate + +clean: + rm -rf _site + +html: clean + $(UV) run sphinx-build -E -b dirhtml -c sphinx . _site -W --keep-going -n + +assemble: + $(UV) run bash ci/download_from_s3.sh + $(UV) run bash ci/post-process.sh + $(UV) run python scripts/validate_site.py _site --full + +full: html assemble + +lint: + $(UV) run ruff check ci extensions scripts sphinx/conf.py tests + $(UV) run ruff format --check ci extensions scripts sphinx/conf.py tests + +test: + $(UV) run pytest + +validate: + $(UV) run python scripts/validate_site.py _site + +check: lint test html validate + +serve: + $(UV) run python -m http.server $(PORT) --bind 0.0.0.0 --directory _site diff --git a/README.md b/README.md index af1a0a8631f..814fb0106e8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,55 @@ -# RAPIDS Docs +# NVIDIA RAPIDS Documentation -Jekyll site for RAPIDS documentation. +This repository contains the source for the +[NVIDIA RAPIDS documentation portal](https://docs.rapids.ai/). The portal is +built with Sphinx and the NVIDIA Sphinx theme. -https://docs.rapids.ai +## Build the portal + +Install [uv](https://docs.astral.sh/uv/), then run: + +```shell +make html +make serve +``` + +The rendered portal is written to `_site`. The server uses port 8000 by default; +override it with `PORT` (for example, `make serve PORT=8080`). + +## Build the complete site + +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: + +```shell +AWS_PROFILE=rapids-docs make full +``` + +This preserves the stable, latest, nightly, and legacy aliases and applies the +RAPIDS library/version selectors to the imported documentation. + +## Validation + +```shell +make check +``` + +This runs Python linting, unit tests, a warning-free Sphinx build, and output +validation. + +Pull requests opened against `rapidsai/docs` are copied to a +`pull-request/` 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 portal-only preview. Merges to `main` continue to deploy the production site. + +## Repository layout + +- Portal content, data, includes, and assets retain their established paths at + the repository root. +- `sphinx/` contains the Sphinx configuration, templates, and theme overrides. +- `extensions/` contains the portal's data-rendering and publication extension. +- `ci/` downloads and post-processes versioned API and deployment documentation. +- `scripts/` and `tests/` validate rendered routes, content, and publication + behavior. diff --git a/_config.yml b/_config.yml deleted file mode 100644 index 19896d9c2fc..00000000000 --- a/_config.yml +++ /dev/null @@ -1,57 +0,0 @@ -# theme used -remote_theme: pmarsceill/just-the-docs -#theme: just-the-docs - -title: RAPIDS Docs -description: RAPIDS demo, process, and technical documentation. -baseurl: "/" # the subpath of your site, e.g. /blog -url: "https://docs.rapids.ai" - -permalink: pretty -exclude: - - CONTRIBUTING.md - - README.md - - release_checklist.md - - ci/ - - node_modules/ - - package.json - - package-lock.json - - Gemfile - - Gemfile.lock - - .ruff_cache/ -include: - - _sources - - _static - - _images - - _redirects - - _sphinx_javascript_frameworks_compat.js - -collections: - notices: - output: true - -aux_links: - "View Docs on GitHub": - - "https://github.com/rapidsai/docs" - -nav_external_links: - - title: Deployment Guides - url: /deployment/stable/ - -social: - twitter: - name: Twitter - username: rapidsai - url: https://twitter.com/rapidsai - fa-icon-class: fab fa-twitter - slack: - name: Slack - url: https://rapids.ai/slack-invite - fa-icon-class: fab fa-slack - stack-overflow: - name: Stack Overflow - url: https://stackoverflow.com/tags/rapids - fa-icon-class: fab fa-stack-overflow - -# Enable or disable the site search -search_enabled: true diff --git a/_drafts/maintainers/artifacts.md b/_drafts/maintainers/artifacts.md deleted file mode 100644 index d9267439a46..00000000000 --- a/_drafts/maintainers/artifacts.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: default -nav_order: 4 -parent: RAPIDS Maintainer Docs -title: Project Artifacts ---- - -# Artifacts - -## Overview - -... - -### Intended audience - -Operations -{: .label .label-purple} - -## Conda packages - -... - -## Pip packages - -... - -## Docker containers - -... - -## Continuous integration - -... diff --git a/_drafts/maintainers/permissions.md b/_drafts/maintainers/permissions.md deleted file mode 100644 index be8ed7a65fb..00000000000 --- a/_drafts/maintainers/permissions.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: default -nav_order: 3 -parent: RAPIDS Maintainer Docs -title: Permissions ---- - -# Permissions - - -## Overview - -... - -### Intended audience - -Operations -{: .label .label-purple} - -## Read - -... - -## Write - -... - -## Admin - -... diff --git a/_drafts/maintainers/projectboards.md b/_drafts/maintainers/projectboards.md deleted file mode 100644 index 1ac8a866af7..00000000000 --- a/_drafts/maintainers/projectboards.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: default -nav_order: 2 -parent: RAPIDS Maintainer Docs -title: Project Boards ---- - -# Project Boards - - -## Overview - -... - -### Intended audience - -Operations -{: .label .label-purple} - -## Release Planning - -... - -## Issue Triage - -... - -## Release Delivery - -... diff --git a/_drafts/maintainers/readthedocs.md b/_drafts/maintainers/readthedocs.md deleted file mode 100644 index a8aebe2cd36..00000000000 --- a/_drafts/maintainers/readthedocs.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: default -nav_order: 5 -parent: RAPIDS Maintainer Docs -title: Read the Docs ---- - -# Read the docs - -## Overview - -... - -### Intended audience - -Operations -{: .label .label-purple} - -## Configuration - -... diff --git a/_drafts/maintainers/structure.md b/_drafts/maintainers/structure.md deleted file mode 100644 index fe2b8982994..00000000000 --- a/_drafts/maintainers/structure.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: default -nav_order: 1 -parent: RAPIDS Maintainer Docs -title: Project Structure ---- - -# Projects - -## Overview - -... - -### Intended audience - -Operations -{: .label .label-purple} - -### Files - -### README - -... - -### CONTRIBUTING - -... - -### CHANGELOG - -... diff --git a/_includes/api-docs.html b/_includes/api-docs.html deleted file mode 100644 index bfa66cdae21..00000000000 --- a/_includes/api-docs.html +++ /dev/null @@ -1,25 +0,0 @@ - -{% for lib in include.data %} -{% assign api = lib[1] %} -{% if api.hidden != true %} -{% comment %} HACK: below operation returns an array of stable/nightly/legacy values only if they're enabled in docs.yml. see issue #97 {% endcomment %} -{% assign versions = api.versions | sort | where_exp: "item", "item[1] == 1" | join: "" | split: "1" | reverse %} -### {{ api.name }} -{{ api.desc }} -#### DOCS {% for version_name in versions -%} - {%- if api.version-overrides -%} - **[{{ version_name }} ({{ api.version-overrides[version_name] }})](/api/{{ api.path }}/{{ version_name }})** - {%- elsif api.name == "libucxx" or api.name == "UCXX" -%} - **[{{ version_name }} ({{ site.data.releases[version_name].ucxx_version }})](/api/{{ api.path }}/{{ version_name }})** - {%- else -%} - **[{{ version_name }} ({{ site.data.releases[version_name].version }})](/api/{{ api.path }}/{{ version_name }})** - {%- endif -%} - {%- unless forloop.last %} | {% endunless -%} -{%- endfor %} - -#### LINKS {% if api.cllink %} **[changelog]({{ api.cllink }}){:target="_blank"}** | {% endif %} **[github]({{ api.ghlink }}){:target="_blank"}** -{: .mb-7 } -{% endif %} -{% endfor %} diff --git a/_includes/bokeh.html b/_includes/bokeh.html index 60141c38b3c..0db103944bd 100644 --- a/_includes/bokeh.html +++ b/_includes/bokeh.html @@ -15,7 +15,7 @@ Bokeh.safely(function () { (function (root) { function embed_document(root) { - const docs_json = document.getElementById('12280').textContent; + const docs_json = root.rapidsStackPanelPanes(document.getElementById('12280').textContent); const render_items = [{ "docid": "be8ea7fa-c482-4932-a1a7-5c9577aec07d", "root_ids": ["9175", "9216"], "roots": { "9175": "1bd788b2-2761-45b2-ae08-2caece4b658e", "9216": "6035a5f3-9a74-444c-a581-c1fdfdc020b4" } }]; root.Bokeh.embed.embed_items(docs_json, render_items); } diff --git a/_includes/datashader.html b/_includes/datashader.html index 6225c62d915..8032ded0acb 100644 --- a/_includes/datashader.html +++ b/_includes/datashader.html @@ -15,7 +15,7 @@ Bokeh.safely(function () { (function (root) { function embed_document(root) { - const docs_json = document.getElementById('8788').textContent; + const docs_json = root.rapidsStackPanelPanes(document.getElementById('8788').textContent); const render_items = [{ "docid": "ad2f45c0-da49-4f5b-be5f-3406fce1fc1e", "root_ids": ["8756", "8768"], "roots": { "8756": "cf6d710b-1908-4b9d-9787-ff5f9bb4ad79", "8768": "cfb375e0-fabb-4d61-a429-60051184efd6" } }]; root.Bokeh.embed.embed_items(docs_json, render_items); } diff --git a/_includes/gpu-labels-table-row.html b/_includes/gpu-labels-table-row.html deleted file mode 100644 index 071ea2d6b9e..00000000000 --- a/_includes/gpu-labels-table-row.html +++ /dev/null @@ -1,12 +0,0 @@ - - - - linux-{{include.arch}}-gpu-{{include.gpu|downcase}}-{{include.version}}-1 - - {{include.gpu}} - {{include.driver}} - 1 - diff --git a/_includes/gpu-labels-table.html b/_includes/gpu-labels-table.html deleted file mode 100644 index 8bf1267dffd..00000000000 --- a/_includes/gpu-labels-table.html +++ /dev/null @@ -1,19 +0,0 @@ - - - - - - - - - - - - {% include gpu-labels-table-row.html arch="amd64" gpu="V100" driver=earliest_driver_version version="earliest" %} - {% include gpu-labels-table-row.html arch="amd64" gpu="V100" driver=latest_driver_version version="latest" %} - {% include gpu-labels-table-row.html arch="arm64" gpu="A100" driver=latest_driver_version version="latest" %} - {% include gpu-labels-table-row.html arch="amd64" gpu="T4" driver=latest_driver_version version="latest" %} - -
LabelGPUDriver Version# of GPUs
diff --git a/_includes/head.html b/_includes/head.html deleted file mode 100644 index 98b1aaa1ef1..00000000000 --- a/_includes/head.html +++ /dev/null @@ -1,99 +0,0 @@ - - - - - {% if page.description %} - - - - {% endif %} - - - - - - - - - - - - - - - - - - - {{ page.title }} - {{ site.title }} - - - - - - - - - - - - - - - - {% if site.search_enabled != nil %} - - {% endif %} - - - - - - - - diff --git a/_includes/holoviews.html b/_includes/holoviews.html index a9fa78f184c..1b745794deb 100644 --- a/_includes/holoviews.html +++ b/_includes/holoviews.html @@ -15,7 +15,7 @@ Bokeh.safely(function () { (function (root) { function embed_document(root) { - const docs_json = document.getElementById('4808').textContent; + const docs_json = root.rapidsStackPanelPanes(document.getElementById('4808').textContent); const render_items = [{ "docid": "3da20d72-bb10-4dad-8c67-9770ce102c17", "root_ids": ["1002", "1078"], "roots": { "1002": "b48c307e-9b2d-4ab7-9c71-fbce2a52bf4d", "1078": "ef5a0967-6748-4ecf-88c9-f5ba27a4dab0" } }]; root.Bokeh.embed.embed_items(docs_json, render_items); } diff --git a/_includes/hvplot.html b/_includes/hvplot.html index 57fd369e6c2..7c8660ae86e 100644 --- a/_includes/hvplot.html +++ b/_includes/hvplot.html @@ -15,7 +15,7 @@ Bokeh.safely(function () { (function (root) { function embed_document(root) { - const docs_json = document.getElementById('8755').textContent; + const docs_json = root.rapidsStackPanelPanes(document.getElementById('8755').textContent); const render_items = [{ "docid": "b0727922-be35-4515-982e-b49ca8fa100b", "root_ids": ["4809", "4887"], "roots": { "4809": "b1afe886-1efe-473f-b5b3-b36a7f08c990", "4887": "2d8c4606-21c2-4451-a7e4-8bcd373c50d6" } }]; root.Bokeh.embed.embed_items(docs_json, render_items); } diff --git a/_includes/nav.html b/_includes/nav.html deleted file mode 100644 index 5ddf537efdf..00000000000 --- a/_includes/nav.html +++ /dev/null @@ -1,59 +0,0 @@ - - diff --git a/_includes/plotly.html b/_includes/plotly.html index c1017fd5511..47cc22d91d4 100644 --- a/_includes/plotly.html +++ b/_includes/plotly.html @@ -15,7 +15,7 @@ Bokeh.safely(function () { (function (root) { function embed_document(root) { - const docs_json = document.getElementById('9134').textContent; + const docs_json = root.rapidsStackPanelPanes(document.getElementById('9134').textContent); const render_items = [{ "docid": "976422fb-2b0d-45f8-81cc-46a6add76aa7", "root_ids": ["8789", "8804"], "roots": { "8789": "ec437eae-b74d-4042-8f47-2da685fda62f", "8804": "565aef76-d9e0-425e-805e-6d78328e3e90" } }]; root.Bokeh.embed.embed_items(docs_json, render_items); } diff --git a/_includes/seaborn.html b/_includes/seaborn.html index bdfb8f53fce..eb7b4a2736e 100644 --- a/_includes/seaborn.html +++ b/_includes/seaborn.html @@ -15,7 +15,7 @@ Bokeh.safely(function () { (function (root) { function embed_document(root) { - const docs_json = document.getElementById('12346').textContent; + const docs_json = root.rapidsStackPanelPanes(document.getElementById('12346').textContent); const render_items = [{ "docid": "fb398535-f4eb-4012-b6fe-cc28dce90368", "root_ids": ["12281", "12293"], "roots": { "12281": "97a50a14-c50a-4103-8735-b007cde7a0fe", "12293": "bc6f7339-30dc-44ba-a622-1960b0855426" } }]; root.Bokeh.embed.embed_items(docs_json, render_items); } diff --git a/_includes/selector.html b/_includes/selector.html index 787459e5402..24069595cc2 100644 --- a/_includes/selector.html +++ b/_includes/selector.html @@ -10,74 +10,122 @@ } .selector-bg { - background-color: #9943ff; - padding: 1rem; - border-radius: 5px; + background: var(--pst-color-surface); + border: 1px solid var(--pst-color-border); + border-top: 4px solid var(--nv-color-green); + border-radius: 0.25rem; + box-shadow: 0 0.125rem 0.5rem color-mix(in srgb, var(--pst-color-shadow) 55%, transparent); + padding: 1.25rem; } .selector .options-section { display: flex; flex-direction: row; flex-wrap: nowrap; + margin-bottom: 0.3rem; } - .selector .options-section-specific { + .selector .options-section-additional { + display: grid; + grid-template-columns: max-content repeat(4, minmax(0, 1fr)); + column-gap: 0.35rem; + row-gap: 0.25rem; + margin: 0.4rem 0 0.5rem; + } + + .selector .options .options-section-additional .option-label { + align-self: center; + grid-row: span 2; + line-height: 1.2; + margin: 0 0.35em 0 0; + max-width: 6.5rem; + white-space: normal; + width: auto; + } + + .selector .options-section-additional .option { + align-items: center; + display: flex; + font-size: 0.8rem; + justify-content: center; + line-height: 1.25; + margin: 0; + min-height: 1.9rem; + padding: 0.2rem 0.35rem; + text-align: center; + } + + .selector .options-section-packages { + align-items: flex-start; + } + + .selector .option-group { + flex: 1 1 auto; + min-width: 0; + } + + .selector .option-row { display: flex; flex-direction: row; flex-wrap: nowrap; - width: 97%; - margin: 0 auto; } .selector .options .option-label { - color: white; - width: 6em; + color: var(--pst-color-text-base); + flex: 0 0 auto; + width: auto; text-transform: uppercase; - font-weight: 600; - margin-top: 0.6em; - margin-right: 0.6em; + font-size: 0.875rem; + font-weight: 700; + letter-spacing: 0.025em; + margin-top: 0.65em; + margin-right: 0.35em; text-align: right; + white-space: nowrap; } .selector .options .option { - background: #e3e3e3; - color: #3c3c3c; + background: var(--pst-color-background); + border: 1px solid var(--pst-color-border); + color: var(--pst-color-text-base); flex: 1 1; margin: 0.2em; - padding: 0.3em; + padding: 0.45em 0.55em; cursor: pointer; line-height: 1.5em; - box-shadow: 2px 2px 2px rgba(10, 10, 10, 0.4); - border-radius: 2px; + box-shadow: none; + border-radius: 0.25rem; } .selector .options .option:hover, - .selector .options .option.active:hover, .cmd-button:hover { - background: #ffb500; - box-shadow: 1px 1px 0px rgba(10, 10, 10, 0.7); - -webkit-transition: background-color 0.3s ease-in-out; - -moz-transition: background-color 0.3s ease-in-out; - -o-transition: background-color 0.3s ease-in-out; - transition: background-color 0.3s ease-in-out; - transition: box-shadow 0.1s ease-in-out; + background: color-mix(in srgb, var(--nv-color-green) 18%, var(--pst-color-background)); + border-color: var(--nv-color-green); + box-shadow: none; + transition: background-color 0.15s ease-in-out, border-color 0.15s ease-in-out; + } + + .selector .options .option.active:hover { + background: var(--nv-color-green); + border-color: var(--nv-color-green-2); } .selector .options .option:active, .selector .options .option.active:active, .cmd-button:active { - color: #9943ff; + color: var(--pst-color-text-base); } .selector .options .note code { - background: #e3e3e3; - color: #000000; + background: var(--pst-color-background); + border: 1px solid var(--pst-color-border-muted); + color: var(--pst-color-text-base); padding: 0.08em 0.15em; border-radius: 4px; } .selector .options .option-blank { - color: white; + color: var(--pst-color-text-base); flex: 1 1; margin: 0.2em; padding: 0.3em; @@ -94,12 +142,13 @@ } .selector .options .option-notice { - color: #e0e0e0; + color: var(--pst-color-text-base); flex: 1 1; margin: 0.2em; padding: 0.3em; line-height: 1.5em; - background: #424242; + background: var(--pst-color-background); + border-left: 4px solid var(--nv-color-green); } .selector .options .option-notice span { @@ -126,57 +175,74 @@ } .selector .options .active { - background: #36c9dd; - font-weight: 600; - color: #424242; + background: var(--nv-color-green); + border-color: var(--nv-color-green-2); + color: #1a1a1a; + font-weight: 700; } .selector .options .active.advanced { - background: #ffb500; - font-weight: 600; - color: #424242; + background: var(--nv-color-green); + border-color: var(--nv-color-green-2); + color: #1a1a1a; + font-weight: 700; } .selector .options .disabled, .selector .options .perm-disabled { - background: #a785e7 !important; - color: #706880; + background: var(--pst-color-surface) !important; + border-color: var(--pst-color-border-muted); + color: var(--pst-color-text-muted); cursor: not-allowed; + opacity: 0.65; } .cmd { display: flex; - margin-top: 2rem; + gap: 0.35rem; + margin-top: 1rem; } .cmd-label { - color: white; - width: 6em; + color: var(--pst-color-text-base); + flex: 0 0 auto; + width: auto; text-transform: uppercase; - font-weight: 600; + font-size: 0.875rem; + font-weight: 700; + letter-spacing: 0.025em; margin-top: 1rem; - margin-right: 0.6em; vertical-align: top; - text-align: right + text-align: right; + white-space: nowrap; } .cmd-box { + border: 1px solid var(--pst-color-border); cursor: text; + flex: 1 1 auto; + min-width: 0; overflow: auto; - width: calc(100% - 6em); + width: auto; border-radius: 4px; } + .cmd-box pre { + margin: 0; + } + .cmd-button { - background: #e3e3e3; + background: var(--pst-color-background); + border: 1px solid var(--pst-color-primary); border-radius: 0.3rem; - color: #3c3c3c; + color: var(--pst-color-text-base); flex: 1 1; margin: 0.5em; padding: 0.6em; cursor: pointer; line-height: 1.5em; - box-shadow: 2px 2px 2px rgb(10 10 10 / 40%); + box-shadow: none; + text-decoration: none; } .hidden { @@ -214,7 +280,7 @@ } .selector .option.active .fas { - color: #3c3c3c; + color: #1a1a1a; } .option-note { @@ -280,24 +346,27 @@
-
+
RAPIDS Packages
- -
-
-
- +
+ +
+
-
+
Additional Packages