Python (chore): add pytest plugin docs (#551)

Author: alexluck-sift

.github/workflows/python_build_docs.yml

@@ -22,6 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      pull-requests: write
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -72,6 +73,36 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Comment docs preview link on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const marker = '<!-- mike-docs-preview -->';
+            const alias = '${{ steps.version.outputs.alias }}';
+            const version = '${{ steps.version.outputs.version }}';
+            const url = `https://sift-stack.github.io/sift/python/${alias}/`;
+            const body = [
+              marker,
+              `**Python docs preview:** ${url}`,
+              ``,
+              `Deployed from \`${version}\`. The link may take up to a minute to become live as GitHub Pages propagates.`,
+            ].join('\n');
+
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner, repo, issue_number, per_page: 100,
+            });
+            const existing = comments.find(c => c.body && c.body.includes(marker));
+
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }
+
   cleanup_docs:
     if: github.event.action == 'closed'
     runs-on: ubuntu-latest

python/docs/examples/index.md

@@ -6,6 +6,7 @@ This section contains interactive Jupyter notebook examples demonstrating how to
 
 - **[Basic Usage](basic.ipynb)** - Introduction to the Sift Python client, covering basic operations and API usage
 - **[Data Ingestion](ingestion.ipynb)** - Learn how to ingest telemetry data into Sift using various methods
+- **[Pytest Plugin](pytest_plugin.md)** - Turn a pytest run into a Sift TestReport with measurements, nested steps, and pass/fail outcomes
 
 ## Running Examples Locally