Python/mkdocs init

.github/workflows/python_build_docs.yml

@@ -0,0 +1,118 @@
+name: Build and Deploy Python Docs (Dev)
+
+on:
+  pull_request:
+    types: [opened, synchronize, closed]
+    paths:
+      - 'python/docs/**'
+      - 'python/lib/**'
+      - 'python/mkdocs.yml'
+      - 'python/pyproject.toml'
+  workflow_dispatch:
+    inputs:
+      deploy_to_dev:
+        description: 'Deploy to dev alias using commit hash as version'
+        required: false
+        default: true
+        type: boolean
+
+jobs:
+  build_docs:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          cd python
+          pip install -e .[docs,development]
+
+      - name: Extract version
+        id: version
+        run: |
+          # Use commit hash as version for dev deployments
+          VERSION=$(git rev-parse --short HEAD)
+
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            # Use PR number as alias for PR deployments
+            ALIAS="pr-${{ github.event.number }}"
+          else
+            # Use 'dev' for manual workflow dispatch
+            ALIAS="dev"
+          fi
+
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "alias=$ALIAS" >> $GITHUB_OUTPUT
+          echo "Dev deployment - Version: $VERSION, Alias: $ALIAS"
+
+      - name: Fetch gh-pages branch
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy docs with mike
+        run: |
+          cd python
+          # Deploy dev/PR docs with hidden property to hide from version dropdown
+          mike deploy ${{ steps.version.outputs.alias }} --push --update-aliases --prop-set hidden=true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  cleanup_docs:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          cd python
+          pip install -e .[docs,development]
+
+      - name: Fetch gh-pages branch
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Delete PR docs
+        run: |
+          cd python
+          PR_ALIAS="pr-${{ github.event.number }}"
+          echo "Deleting docs for: $PR_ALIAS"
+
+          # Check if the PR docs exist before trying to delete
+          if mike list | grep -q "$PR_ALIAS"; then
+            mike delete "$PR_ALIAS" --push
+            echo "Successfully deleted docs for $PR_ALIAS"
+          else
+            echo "No docs found for $PR_ALIAS, nothing to delete"
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/python_release.yaml

@@ -87,4 +87,89 @@ jobs:
             echo "Uploading archive: $archive"
             gh release upload "$TAG_NAME" "$archive" --clobber
           done
+
+  deploy-docs:
+    name: Deploy Documentation
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          cd python
+          pip install -e .[docs,development]
+
+      - name: Extract version and check if stable
+        id: version
+        run: |
+          # Extract version from tag (everything after 'python/')
+          FULL_VERSION=${GITHUB_REF#refs/tags/python/}
+          echo "Full version from tag: $FULL_VERSION"
+
+          # Extract major.minor from version (drop patch)
+          if [[ "$FULL_VERSION" =~ ^v?([0-9]+)\.([0-9]+)\.[0-9]+(.*)?$ ]]; then
+            MAJOR=${BASH_REMATCH[1]}
+            MINOR=${BASH_REMATCH[2]}
+            SUFFIX=${BASH_REMATCH[3]}
+            VERSION="v${MAJOR}.${MINOR}"
+
+            # Check if this is a stable release (no suffix like -alpha, -beta, -rc)
+            if [[ -z "$SUFFIX" ]]; then
+              # Stable release - use 'latest' alias and make visible
+              ALIAS="latest"
+              HIDDEN="false"
+              echo "Stable release detected: $FULL_VERSION -> $VERSION"
+            else
+              # Pre-release (alpha, beta, rc) - no 'latest' alias and hide from dropdown
+              VERSION="${VERSION}${SUFFIX}"
+              ALIAS=""
+              HIDDEN="true"
+              echo "Pre-release detected: $FULL_VERSION -> $VERSION"
+            fi
+          else
+            echo "Error: Could not parse version format: $FULL_VERSION"
+            exit 1
+          fi
+
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "alias=$ALIAS" >> $GITHUB_OUTPUT
+          echo "hidden=$HIDDEN" >> $GITHUB_OUTPUT
+          echo "Final - Version: $VERSION, Alias: $ALIAS, Hidden: $HIDDEN"
+
+      - name: Fetch gh-pages branch
+        run: git fetch origin gh-pages --depth=1
+
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy docs with mike
+        run: |
+          cd python
+          VERSION="${{ steps.version.outputs.version }}"
+          ALIAS="${{ steps.version.outputs.alias }}"
+          HIDDEN="${{ steps.version.outputs.hidden }}"
 
+          # Always deploy the full version first, but hide it
+          echo "Deploying full version $FULL_VERSION (hidden)"
+          mike deploy "$FULL_VERSION" --push --prop-set hidden=true
+
+          if [[ "$HIDDEN" == "false" ]]; then
+            # Stable release: deploy abbreviated version with latest alias, visible in dropdown
+            echo "Deploying stable release $VERSION with $ALIAS alias"
+            mike deploy "$VERSION" "$ALIAS" --push --update-aliases
+          fi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

python/docs/index.md

@@ -0,0 +1,68 @@
+# Sift Python Client Library
+Welcome to the official Python client library for Sift! This library provides a high-level Python API on top of Sift's protocol buffers, designed to ergonomically interface with the Sift gRPC API and simplify the process of streaming data.
+
+Sift provides official client libraries for select languages, designed to simplify the process of streaming data over gRPC. These client libraries utilize ingestion-config-based streaming to facilitate data transmission.
+
+Check out the [repository](https://github.com/sift-stack/sift) for a list of all available client libraries.
+
+## Installation
+
+To install the Sift Python library:
+
+```bash
+pip install sift-stack-py
+```
+
+## API Documentation
+
+This documentation covers two Python APIs for interacting with Sift:
+
+### Sift Py API
+
+The original low-level Python API that provides direct access to Sift's protocol buffer interfaces. 
+
+Browse the [**Sift Py API**][sift_py] section for complete reference documentation.
+
+**Use this API if you need:**
+
+- Direct protocol buffer access
+- Fine-grained control over gRPC connections  
+- Legacy compatibility with existing code
+
+### Sift Client API (New)   
+
+!!! warning
+    The Sift Client is experimental and is subject to change.
+
+
+The modern, high-level client library that provides all the ergonomic features missing from the original API. This new client offers intuitive Python interfaces, strong type safety, automatic connection management, and both synchronous and asynchronous support. 
+
+Explore the [**Sift Client API (New)**][sift_client] section for the complete API reference.
+
+**Key improvements over Sift Py:**
+
+- **Ergonomic Design** - Pythonic interfaces instead of raw protocol buffers
+- **Type Safety** - Full type hints and Pydantic model validation
+- **Dual APIs** - Both sync and async support for all operations
+- **Auto Connection Management** - No manual gRPC connection handling
+- **Rich Object Models** - Immutable types with convenient methods
+- **Modern Patterns** - Context managers, iterators, and Python best practices
+
+
+## Getting help
+
+- **API Reference** - Browse the complete API documentation in the navigation
+- **Examples** - Check out code examples throughout the documentation
+- **GitHub** - Visit our [repository](https://github.com/sift-stack/sift) for issues and contributions
+
+## What's next?
+
+Ready to dive deeper? Explore the API documentation to learn about:
+
+- **Sift Resources** - Creating, updating, and organizing your assets and other data
+- **Data Streaming** - Efficient methods for ingesting data
+- **Advanced Filtering** - Powerful query capabilities
+- **Error Handling** - Best practices for robust applications
+- **Performance Optimization** - Tips for high-throughput scenarios
+
+Get started by exploring the API reference in the navigation menu!

python/docs/overrides/main.html

@@ -0,0 +1,10 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+You're not viewing the latest version.
+<a href="{{ '../' ~ base_url }}">
+
+
+    <strong>Click here to go to latest.</strong>
+</a>
+{% endblock %}

python/docs/overrides/partials/logo.html

@@ -0,0 +1,2 @@
+<img id='logo_dark_mode' src='{{ config.theme.logo_dark_mode | url }}' alt='logo'>
+<img id='logo_light_mode' src='{{ config.theme.logo_light_mode | url }}' alt='logo'>