Capture deprecated API warnings from tutorial builds

Author: svekars

.github/workflows/_build-tutorials-base.yml

@@ -158,6 +158,7 @@ jobs:
           JOB_TYPE: manager
           COMMIT_SOURCE: ${{ github.ref }}
           GITHUB_PYTORCHBOT_TOKEN: ${{ secrets.PYTORCHBOT_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           USE_NIGHTLY: ${{ inputs.USE_NIGHTLY }}
         run: |
           set -ex
@@ -172,6 +173,7 @@ jobs:
             -e JOB_TYPE \
             -e COMMIT_SOURCE \
             -e GITHUB_PYTORCHBOT_TOKEN \
+            -e GITHUB_TOKEN \
             -e USE_NIGHTLY \
             --env-file="/tmp/github_env_${GITHUB_RUN_ID}" \
             --tty \
@@ -184,6 +186,14 @@ jobs:
 
           docker exec -u ci-user -t "${container_name}" sh -c ".jenkins/build.sh"
 
+      - name: Upload API deprecation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-deprecation-report
+          path: tutorials/_build/api_report.md
+          if-no-files-found: ignore
+
       - name: Upload docs preview
         uses: seemethere/upload-artifact-s3@v5
         if: ${{ github.event_name == 'pull_request' }}

.jenkins/build.sh

@@ -69,7 +69,8 @@ if [[ "${JOB_TYPE}" == "worker" ]]; then
   export FILES_TO_RUN
 
   # Step 3: Run `make docs` to generate HTML files and static files for these tutorialis
-  make docs
+  export PYTHONWARNINGS="all::DeprecationWarning,all::FutureWarning"
+  make docs 2>&1 | tee _build/build.log
 
   # Step 3.1: Run the post-processing script:
   python .jenkins/post_process_notebooks.py
@@ -125,6 +126,9 @@ if [[ "${JOB_TYPE}" == "worker" ]]; then
   bash $DIR/remove_invisible_code_block_batch.sh docs
   python .jenkins/validate_tutorials_built.py
 
+  # Step 5.1: Generate API deprecation report from build warnings
+  python -m tools.deprecation_checker.api_report --build-log _build/build.log -o _build/api_report.md || true
+
   # Step 6: Copy generated files to S3, tag with commit ID
   if [ "${UPLOAD:-0}" -eq 1 ]; then
     7z a worker_${WORKER_ID}.7z docs
@@ -156,6 +160,9 @@ elif [[ "${JOB_TYPE}" == "manager" ]]; then
   # Step 5.1: Run post-processing script on .ipynb files:
   python .jenkins/post_process_notebooks.py
 
+  # Step 5.2: Create/update GitHub Issue with deprecation findings
+  python -m tools.deprecation_checker.api_report --build-log _build/build.log --create-issue || true
+
   # Step 6: Copy generated HTML files and static files to S3
   7z a manager.7z docs
   awsv2 s3 cp manager.7z s3://${BUCKET_NAME}/${BUILD_PREFIX}/${COMMIT_ID}/manager.7z

tools/__init__.py

@@ -0,0 +1,283 @@
+"""Generate Markdown deprecation reports and optionally file GitHub Issues.
+
+Usage::
+
+    # Local report to stdout
+    python -m tools.deprecation_checker.api_report --build-log _build/build.log
+
+    # Local report written to a file
+    python -m tools.deprecation_checker.api_report --build-log _build/build.log -o _build/api_report.md
+
+    # Create / update a GitHub Issue (requires GITHUB_TOKEN)
+    python -m tools.deprecation_checker.api_report --build-log _build/build.log --create-issue
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+from collections import defaultdict
+from pathlib import Path
+from typing import List
+
+from .build_warning_parser import BuildWarning, is_tutorial_source, parse_log
+
+# --------------------------------------------------------------------------- #
+# Constants
+# --------------------------------------------------------------------------- #
+
+REPO_OWNER = "pytorch"
+REPO_NAME = "tutorials"
+ISSUE_LABEL = "docs-agent-deprecations"
+ISSUE_TITLE = "[CI] Deprecated API usage in tutorials"
+ISSUE_CC = "svekars"
+
+# --------------------------------------------------------------------------- #
+# Markdown report generation
+# --------------------------------------------------------------------------- #
+
+
+def _summary_table(warnings: List[BuildWarning]) -> str:
+    """Build a Markdown table summarising warning counts per file."""
+    counts: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+    for w in warnings:
+        counts[w.file][w.category] += 1
+
+    lines = [
+        "| Tutorial file | DeprecationWarning | FutureWarning | Total |",
+        "|---|---:|---:|---:|",
+    ]
+    for file in sorted(counts):
+        dep = counts[file].get("DeprecationWarning", 0)
+        fut = counts[file].get("FutureWarning", 0)
+        lines.append(f"| `{file}` | {dep} | {fut} | {dep + fut} |")
+
+    total_dep = sum(c.get("DeprecationWarning", 0) for c in counts.values())
+    total_fut = sum(c.get("FutureWarning", 0) for c in counts.values())
+    lines.append(f"| **Total** | **{total_dep}** | **{total_fut}** | **{total_dep + total_fut}** |")
+    return "\n".join(lines)
+
+
+def _findings_section(warnings: List[BuildWarning]) -> str:
+    """Detailed findings grouped by file, sorted by line number."""
+    by_file: dict[str, list[BuildWarning]] = defaultdict(list)
+    for w in warnings:
+        by_file[w.file].append(w)
+
+    sections: list[str] = []
+    for file in sorted(by_file):
+        items = sorted(by_file[file], key=lambda w: w.lineno)
+        parts = [f"### `{file}`\n"]
+        for w in items:
+            parts.append(
+                f"- **Line {w.lineno}** ({w.category}): {w.message}"
+            )
+        sections.append("\n".join(parts))
+
+    return "\n\n".join(sections)
+
+
+def generate_report(warnings: List[BuildWarning]) -> str:
+    """Return a full Markdown report string."""
+    if not warnings:
+        return (
+            "# API Deprecation Report\n\n"
+            "No `DeprecationWarning` or `FutureWarning` detected in this build. :tada:"
+        )
+
+    tutorial_warnings = [w for w in warnings if is_tutorial_source(w.file)]
+    other_warnings = [w for w in warnings if not is_tutorial_source(w.file)]
+
+    parts = [
+        "# API Deprecation Report",
+        "",
+        f"**{len(warnings)}** unique deprecation/future warnings found in this build.",
+        "",
+    ]
+
+    if tutorial_warnings:
+        parts += [
+            "## Summary (tutorial sources)",
+            "",
+            _summary_table(tutorial_warnings),
+            "",
+            "## Findings",
+            "",
+            _findings_section(tutorial_warnings),
+            "",
+        ]
+
+    if other_warnings:
+        parts += [
+            "## Warnings from dependencies / non-tutorial code",
+            "",
+            _findings_section(other_warnings),
+            "",
+        ]
+
+    return "\n".join(parts)
+
+
+# --------------------------------------------------------------------------- #
+# GitHub Issue creation / update
+# --------------------------------------------------------------------------- #
+
+
+def _gh_api(
+    method: str,
+    endpoint: str,
+    token: str,
+    body: dict | None = None,
+) -> dict:
+    """Minimal GitHub REST API helper using only stdlib."""
+    url = f"https://api.github.com{endpoint}"
+    data = json.dumps(body).encode() if body else None
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method=method,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {token}",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    with urllib.request.urlopen(req) as resp:
+        return json.loads(resp.read())
+
+
+def _ensure_label(token: str) -> None:
+    """Create the issue label if it doesn't exist yet."""
+    try:
+        _gh_api(
+            "POST",
+            f"/repos/{REPO_OWNER}/{REPO_NAME}/labels",
+            token,
+            {"name": ISSUE_LABEL, "color": "d93f0b", "description": "Auto-generated deprecation report from CI"},
+        )
+    except urllib.error.HTTPError as exc:
+        if exc.code == 422:
+            pass  # label already exists
+        else:
+            raise
+
+
+def _find_existing_issue(token: str) -> int | None:
+    """Return the issue number of the existing open deprecation issue, or None."""
+    results = _gh_api(
+        "GET",
+        f"/repos/{REPO_OWNER}/{REPO_NAME}/issues?labels={ISSUE_LABEL}&state=open&per_page=1",
+        token,
+    )
+    if results:
+        return results[0]["number"]
+    return None
+
+
+def create_or_update_issue(report_body: str, token: str) -> str:
+    """Create or update the deprecation GitHub Issue. Returns the issue URL."""
+    _ensure_label(token)
+    existing = _find_existing_issue(token)
+
+    body = f"cc: @{ISSUE_CC}\n\n{report_body}"
+
+    if existing:
+        result = _gh_api(
+            "PATCH",
+            f"/repos/{REPO_OWNER}/{REPO_NAME}/issues/{existing}",
+            token,
+            {"body": body},
+        )
+        return result["html_url"]
+    else:
+        result = _gh_api(
+            "POST",
+            f"/repos/{REPO_OWNER}/{REPO_NAME}/issues",
+            token,
+            {
+                "title": ISSUE_TITLE,
+                "body": body,
+                "labels": [ISSUE_LABEL],
+            },
+        )
+        return result["html_url"]
+
+
+def close_issue_if_open(token: str) -> str | None:
+    """Close the deprecation issue if one is open. Returns the URL or None."""
+    existing = _find_existing_issue(token)
+    if not existing:
+        return None
+    result = _gh_api(
+        "PATCH",
+        f"/repos/{REPO_OWNER}/{REPO_NAME}/issues/{existing}",
+        token,
+        {
+            "state": "closed",
+            "body": f"cc: @{ISSUE_CC}\n\n"
+                    "All `DeprecationWarning` and `FutureWarning` issues have been resolved. "
+                    "This issue will reopen automatically if new deprecations are detected.",
+        },
+    )
+    return result["html_url"]
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate an API deprecation report from a Sphinx build log.",
+    )
+    parser.add_argument(
+        "--build-log",
+        required=True,
+        help="Path to the build log file (e.g. _build/build.log).",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Write the Markdown report to this file instead of stdout.",
+    )
+    parser.add_argument(
+        "--create-issue",
+        action="store_true",
+        help="Create or update a GitHub Issue with the report (requires GITHUB_TOKEN).",
+    )
+    args = parser.parse_args(argv)
+
+    warnings = parse_log(args.build_log)
+    report = generate_report(warnings)
+
+    if args.output:
+        Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.output).write_text(report)
+        print(f"Report written to {args.output}")
+    else:
+        print(report)
+
+    if args.create_issue:
+        token = os.environ.get("GITHUB_TOKEN", "")
+        if not token:
+            print("WARNING: GITHUB_TOKEN not set — skipping issue creation.", file=sys.stderr)
+            return
+        if not warnings:
+            url = close_issue_if_open(token)
+            if url:
+                print(f"All warnings resolved — closed issue: {url}")
+            else:
+                print("No warnings found and no open issue to close.")
+            return
+        url = create_or_update_issue(report, token)
+        print(f"GitHub Issue: {url}")
+
+
+if __name__ == "__main__":
+    main()