Merge branch 'main' of https://github.com/microsoft/PyRIT into hawestra/text_adaptive_scenario

Author: hannahwestra25

.github/docs-versions.yml

@@ -0,0 +1,23 @@
+# Versions exposed on the PyRIT documentation site.
+#
+# This file is the single source of truth consumed by:
+#   * .github/workflows/docs.yml   - builds each version listed below
+#   * the version picker injected into every doc page
+#   * doc/contributing/10_release_process.md - tells the releaser to edit this file
+#
+# To add a new release version: append an entry under `versions:`, and update
+# `default:` / `stable:` if the new release should become the landing page.
+
+default: "0.13.0"  # served at the site root (microsoft.github.io/PyRIT/)
+stable: "0.13.0"   # served at /stable/ and shown as "(stable)" in the picker
+
+versions:
+  - slug: latest
+    name: "latest (dev, main)"
+    ref: main
+  - slug: "0.13.0"
+    name: "0.13.0"
+    ref: releases/v0.13.0
+  - slug: "0.12.1"
+    name: "0.12.1"
+    ref: releases/v0.12.1

.github/workflows/docs.yml

@@ -3,82 +3,255 @@ name: build-book
 on:
   push:
     branches:
-      - "main"
+      - main
+      - "releases/v*"
+    paths-ignore:
+      - "**/*.md"
+      - ".github/ISSUE_TEMPLATE/**"
   pull_request:
     branches:
-      - "main"
-      - "release/**"
+      - main
+      - "releases/**"
+    paths:
+      - ".github/workflows/docs.yml"
+      - ".github/docs-versions.yml"
+      - "build_scripts/inject_version_picker.py"
+      - "build_scripts/version_picker_assets/**"
+      - "doc/**"
+      - "build_scripts/pydoc2json.py"
+      - "build_scripts/gen_api_md.py"
+      - "pyrit/**"
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+# Permissions for the GH Pages deployment.
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+# One deploy at a time. Don't cancel in-progress production deploys.
 concurrency:
-  group: "pages"
+  group: pages
   cancel-in-progress: false
 
 env:
-  # BASE_URL determines the website path prefix, including CSS & JS assets
-  BASE_URL: /${{ github.event.repository.name }}
+  # All versioned URLs live under /<repo-name>/<slug>/, e.g. /PyRIT/0.13.0/.
+  DOCS_BASE: /${{ github.event.repository.name }}
+  # Manual cache-bust knob. Bump this when the build pipeline changes in a
+  # way that affects the rendered HTML output but isn't captured by the
+  # source-ref SHA -- e.g. bumping python-version, uv version, or changing
+  # build flags in the steps below. Forgetting to bump is harmless (you
+  # just serve a stale cached build for one push); bumping unnecessarily
+  # is also harmless (one extra rebuild).
+  CACHE_VERSION: "v1"
 
-# This job installs dependencies, builds the book, and pushes it to `gh-pages`
 jobs:
-  deploy-book:
+  # ------------------------------------------------------------------
+  # 1. Read .github/docs-versions.yml and turn it into a build matrix.
+  # ------------------------------------------------------------------
+  versions:
+    name: Resolve version matrix
     runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
+    outputs:
+      matrix: ${{ steps.matrix.outputs.matrix }}
+      default: ${{ steps.matrix.outputs.default }}
+      stable: ${{ steps.matrix.outputs.stable }}
+      versions_json: ${{ steps.matrix.outputs.versions_json }}
     steps:
-    - uses: actions/checkout@v6
-
-    # Install dependencies
-    - name: Set up Python 3.11
-      uses: actions/setup-python@v6
-      with:
-        python-version: 3.11
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v7
-      with:
-        # Install a specific version of uv.
-        version: "0.9.17"
-        enable-cache: true
-        cache-dependency-glob: |
-          **/pyproject.toml
-          **/uv.lock
-
-    - name: Install PyRIT with uv
-      run: uv sync --extra all
-
-    # LaTeX toolchain needed for the PDF export (jupyter-book --pdf via xelatex).
-    # Mirrors the ReadTheDocs build so CI catches PDF-only issues (e.g. broken
-    # image paths) instead of letting them silently break the RTD build.
-    - name: Install LaTeX (for PDF export)
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y --no-install-recommends \
-          texlive-xetex \
-          texlive-fonts-recommended \
-          texlive-fonts-extra \
-          texlive-plain-generic \
-          texlive-latex-extra \
-          latexmk
-
-    # Build the book (HTML site + PDF export)
-    - name: Build the book
-      run: |
-        make docs-build-all
-    # Upload the book's HTML as an artifact
-    - name: Upload artifact
-      uses: actions/upload-pages-artifact@v5
-      with:
-        path: "doc/_build/html"
-    - name: Deploy to GitHub Pages
-      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-      id: deployment
-      uses: actions/deploy-pages@v5
+      - uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            .github/docs-versions.yml
+            build_scripts/resolve_docs_matrix.py
+          sparse-checkout-cone-mode: false
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install PyYAML
+        run: pip install --quiet "pyyaml>=6.0"
+
+      - name: Compute matrix
+        id: matrix
+        run: |
+          python build_scripts/resolve_docs_matrix.py \
+            --config .github/docs-versions.yml \
+            --github-output "$GITHUB_OUTPUT"
+
+  # ------------------------------------------------------------------
+  # 2. Build each version in parallel.
+  # ------------------------------------------------------------------
+  build:
+    name: Build ${{ matrix.slug }}
+    needs: versions
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.versions.outputs.matrix) }}
+    env:
+      BASE_URL: ${{ format('/{0}/{1}', github.event.repository.name, matrix.slug) }}
+    steps:
+      - name: Checkout ${{ matrix.ref }}
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ matrix.ref }}
+
+      - name: Resolve commit SHA
+        # matrix.ref is a branch name (e.g. "releases/v0.13.0") that can move,
+        # so resolve to the actual commit SHA we just checked out. This is the
+        # primary cache key component: frozen release branches that don't move
+        # produce identical SHAs and hit the cache forever; main produces a
+        # new SHA on every push so it always rebuilds.
+        id: sha
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore built site from cache
+        # Cache hit -> we skip the entire install + build pipeline and just
+        # upload the restored doc/_build/html as the matrix artifact. Cache
+        # miss -> we do a fresh build and actions/cache saves the result on
+        # job success, so the next run with the same SHA hits.
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: doc/_build/html
+          key: docs-${{ env.CACHE_VERSION }}-${{ matrix.slug }}-${{ steps.sha.outputs.sha }}
+
+      - name: Set up Python 3.13
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.17"
+          enable-cache: true
+          cache-dependency-glob: |
+            **/pyproject.toml
+            **/uv.lock
+
+      - name: Install PyRIT with dev dependencies
+        if: steps.cache.outputs.cache-hit != 'true'
+        # Use `uv sync --frozen` so each release branch installs the exact
+        # versions pinned in its own uv.lock. Frozen branch = frozen deps =
+        # bit-for-bit reproducible rebuild forever.
+        #
+        # Newer release branches (incl. main) use PEP 735 [dependency-groups];
+        # older releases use legacy [project.optional-dependencies]. We pick
+        # the right flag up front by reading pyproject.toml (via stdlib
+        # tomllib) so any uv sync failure surfaces normally instead of being
+        # swallowed by `|| fallback` with stderr redirected to /dev/null.
+        run: |
+          set -euo pipefail
+          choice=$(python -c "
+          import sys, tomllib
+          d = tomllib.loads(open('pyproject.toml').read())
+          if 'dev' in (d.get('dependency-groups') or {}):
+              print('--group dev')
+          elif 'dev' in (d.get('project', {}).get('optional-dependencies') or {}):
+              print('--extra dev')
+          else:
+              print('error: no dev group/extra in pyproject.toml', file=sys.stderr); sys.exit(1)
+          ")
+          echo "Installing with: uv sync --frozen $choice"
+          uv sync --frozen $choice
+
+      - name: Generate API reference (pydoc2json + gen_api_md)
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          source .venv/bin/activate
+          python build_scripts/pydoc2json.py pyrit --submodules -o doc/_api/pyrit_all.json
+          python build_scripts/gen_api_md.py
+
+      - name: Build the static HTML site
+        if: steps.cache.outputs.cache-hit != 'true'
+        # --all builds frontmatter exports (PDF, per doc/myst.yml).
+        # --html is required to produce the static HTML site we deploy.
+        # NOT using --strict because older release branches have known
+        # warnings (e.g. unresolved cross-refs) that aren't worth fixing
+        # retroactively just to satisfy strict mode.
+        working-directory: doc
+        run: |
+          source ../.venv/bin/activate
+          jupyter-book build --all --html
+
+      - name: Upload built site
+        uses: actions/upload-artifact@v4
+        with:
+          name: site-${{ matrix.slug }}
+          path: doc/_build/html
+          retention-days: 7
+          if-no-files-found: error
+
+  # ------------------------------------------------------------------
+  # 3. Compose dist/, inject picker, deploy to GH Pages.
+  # ------------------------------------------------------------------
+  deploy:
+    name: Deploy
+    needs: [versions, build]
+    runs-on: ubuntu-latest
+    # Deploy on push to main, or when triggered manually from main. Skipped
+    # for pushes to release branches (those builds are validation-only) and
+    # for pull requests.
+    if: >-
+      ${{ github.ref == 'refs/heads/main' &&
+          (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            .github/docs-versions.yml
+            build_scripts/inject_version_picker.py
+            build_scripts/version_picker_assets
+            build_scripts/generate_pages_manifest.py
+            build_scripts/compose_docs_dist.py
+          sparse-checkout-cone-mode: false
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install PyYAML
+        run: pip install --quiet "pyyaml>=6.0"
+
+      - name: Download all version artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          pattern: site-*
+
+      - name: Compose dist/
+        # Compose script does everything: stage artifacts into dist/<slug>/,
+        # write per-version pages.json manifests, write top-level versions.json,
+        # write the root + /stable/ redirects, and write 404.html (with the
+        # auto-redirect script that uses the manifest to find the closest
+        # sibling page in the same version).
+        run: |
+          python build_scripts/compose_docs_dist.py \
+            --artifacts-dir artifacts \
+            --dist-dir dist \
+            --config .github/docs-versions.yml \
+            --base "${DOCS_BASE}"
+
+      - name: Inject version picker
+        run: |
+          python build_scripts/inject_version_picker.py \
+            --site-dir dist \
+            --base "${DOCS_BASE}"
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5