Update docs build and version selector works as expected (microsoft#2500)

## Update docs build and version selector works as expected

This PR fixes documentation version selection by making the Sphinx
`version` come from CI (with a sensible local default) and by explicitly
marking the “latest” docs entry as preferred so the version switcher
behaves correctly on `main`.

**Changes:**
- Update Sphinx `conf.py` to source the docs version from
`OLIVE_DOCS_VERSION` (defaulting to `main` for local/dev builds).
- Mark the latest stable version as the preferred target in
`versions.json`.
- Improve the `update_versions_json.py` script to maintain a single
`(latest)` entry, clear stale `preferred` flags, and keep the latest
release positioned directly after `dev (main)`.

### Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and
generated no comments.

| File | Description |
| ---- | ----------- |
| `docs/source/conf.py` | Uses a CI-provided docs version (defaults to
`main`) so `version_match` aligns with the built docs branch/version. |
| `docs/source/_static/versions.json` | Adds `preferred: true` to the
latest stable version to guide the version switcher fallback behavior. |
| `.azure_pipelines/scripts/update_versions_json.py` | Ensures
`(latest)` naming and `preferred` flag are consistently applied and
keeps the latest entry in the expected position. |

## Checklist before requesting a review
- [ ] Add unit tests for this change.
- [ ] Make sure all tests can pass.
- [ ] Update documents if necessary.
- [x] Lint and apply fixes to your code by running `lintrunner -a`
- [ ] Is this a user-facing change? If yes, give a description of this
change to be included in the release notes.

## (Optional) Issue link

Author: shaahji

.azure_pipelines/scripts/update_versions_json.py

@@ -15,25 +15,32 @@ def main():
     with open(versions_file) as f:
         versions = json.load(f)
 
-    # Check if version already exists
-    for v in versions:
-        if v["version"] == new_version:
-            return
+    existing_entry = None
 
-    # Remove "(latest)" from all existing versions
+    # Remove "(latest)" and stale preferred flags from all existing versions.
     for v in versions:
         if "(latest)" in v["name"]:
             v["name"] = v["version"]
-
-    # Insert new version after "dev (main)" with (latest) tag
-    new_entry = {
-        "name": f"{new_version} (latest)",
-        "version": new_version,
-        "url": f"https://microsoft.github.io/Olive/{new_version}/",
-    }
-
-    # Insert after the first entry (dev/main)
-    versions.insert(1, new_entry)
+        v.pop("preferred", None)
+        if v["version"] == new_version:
+            existing_entry = v
+
+    if existing_entry is None:
+        existing_entry = {
+            "name": f"{new_version} (latest)",
+            "version": new_version,
+            "url": f"https://microsoft.github.io/Olive/{new_version}/",
+            "preferred": True,
+        }
+        # Insert after the first entry (dev/main)
+        versions.insert(1, existing_entry)
+    else:
+        existing_entry["name"] = f"{new_version} (latest)"
+        existing_entry["url"] = f"https://microsoft.github.io/Olive/{new_version}/"
+        existing_entry["preferred"] = True
+
+    # Keep the latest release directly after the dev/main entry.
+    versions = [versions[0], existing_entry] + [v for v in versions[1:] if v is not existing_entry]
 
     # Write updated versions.json
     with open(versions_file, "w") as f:

.github/workflows/docs.yml

@@ -35,6 +35,8 @@ jobs:
         python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Build docs
+      env:
+        OLIVE_DOCS_VERSION: main
       run: |
         python -m pip install .
         cd docs
@@ -43,3 +45,62 @@ jobs:
         make html
         make linkcheck
         make schema
+
+    - name: Upload built docs
+      uses: actions/upload-artifact@v4
+      with:
+        name: docs-html
+        path: docs/build/html
+        if-no-files-found: error
+
+  publish:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Download built docs
+      uses: actions/download-artifact@v4
+      with:
+        name: docs-html
+        path: docs-publish
+
+    - name: Publish docs to gh-pages root
+      env:
+        GH_PAGES_DIR: ../gh-pages-worktree
+      run: |
+        set -euxo pipefail
+
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git fetch origin gh-pages
+        rm -rf "$GH_PAGES_DIR"
+        git worktree add "$GH_PAGES_DIR" origin/gh-pages
+
+        cd "$GH_PAGES_DIR"
+        find . -mindepth 1 -maxdepth 1 \
+          ! -name '.git' \
+          ! -name 'CNAME' \
+          ! -name '.nojekyll' \
+          ! -name '.gitignore' \
+          ! -regex './[0-9]+\.[0-9]+\.[0-9]+' \
+          -exec rm -rf {} +
+
+        cp -a "$GITHUB_WORKSPACE/docs-publish/." .
+        touch .nojekyll
+
+        git add -A
+        if git diff --cached --quiet; then
+          echo "No docs changes to publish"
+          exit 0
+        fi
+
+        git commit -m "Publish docs for ${GITHUB_SHA}"
+        git push origin HEAD:gh-pages

docs/source/_static/versions.json

@@ -1,6 +1,11 @@
 [
     { "name": "dev (main)", "version": "main", "url": "https://microsoft.github.io/Olive/" },
-    { "name": "0.12.1 (latest)", "version": "0.12.1", "url": "https://microsoft.github.io/Olive/0.12.1/" },
+    {
+        "name": "0.12.1 (latest)",
+        "version": "0.12.1",
+        "url": "https://microsoft.github.io/Olive/0.12.1/",
+        "preferred": true
+    },
     { "name": "0.12.0", "version": "0.12.0", "url": "https://microsoft.github.io/Olive/0.12.0/" },
     { "name": "0.10.1", "version": "0.10.1", "url": "https://microsoft.github.io/Olive/0.10.1/" },
     { "name": "0.10.0", "version": "0.10.0", "url": "https://microsoft.github.io/Olive/0.10.0/" },

docs/source/conf.py

@@ -19,7 +19,8 @@
 
 project = "Olive"
 copyright = "2023-2026, Olive Dev team"
-version = "0.12.1"
+# The docs version is provided by CI. Default to main for local/dev builds.
+version = os.getenv("OLIVE_DOCS_VERSION", "main")
 release = version
 
 # -- General configuration ---------------------------------------------------