From 770adc0bf95af573958a9b803f4f847e69156444 Mon Sep 17 00:00:00 2001 From: Skylar Brown Date: Thu, 30 Apr 2026 15:52:49 -0700 Subject: [PATCH] ci(docs): replace Sphinx workflows with ProperDocs deploy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SDK ships an auto-generated ProperDocs/MkDocs reference site driven by docs/gen_ref_pages.py + properdocs.yml (landed in release v1.0.0rc22). The existing Sphinx-shaped CI in this repo would have failed on first run because the inputs it depends on (docs/conf.py, the Divio tutorials/how-to/ reference/explanation tree, the Sphinx Makefile) no longer exist. This change replaces docs-deploy.yml with a minimal Pages-deploy workflow that mirrors `make docs-build` (uv run --extra docs properdocs build) and ships the resulting site/ directory through actions/upload-pages-artifact + actions/deploy-pages@v4. Removed: - docs-preview.yml: Sphinx-only PR artifact upload; can be reintroduced later as an MkDocs-based PR preview if useful. - docs-validation.yml: post-deploy live-URL nav check that hard-codes Sphinx-named pages (tutorials/index.html, etc.) which no longer exist. - docs-versioned.yml: mike-based versioned docs; not shipping versioning day one. Mike works fine with MkDocs if/when we want it back. Kept untouched: - sync-changelog-to-docs.yml: independent of the Pages site this workflow deploys. --strict is intentionally OFF on properdocs build to match the Makefile (pre-existing griffe warnings); re-add once those are cleaned. ✨ Created with Claude Code --- .github/workflows/docs-deploy.yml | 188 +++++--------------------- .github/workflows/docs-preview.yml | 159 ---------------------- .github/workflows/docs-validation.yml | 156 --------------------- .github/workflows/docs-versioned.yml | 151 --------------------- 4 files changed, 31 insertions(+), 623 deletions(-) delete mode 100644 .github/workflows/docs-preview.yml delete mode 100644 .github/workflows/docs-validation.yml delete mode 100644 .github/workflows/docs-versioned.yml diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml index 0418cdfe..1e23080b 100644 --- a/.github/workflows/docs-deploy.yml +++ b/.github/workflows/docs-deploy.yml @@ -1,192 +1,66 @@ --- name: Deploy Documentation to GitHub Pages -# Deploy Sphinx documentation to GitHub Pages -# Triggers: main branch push, releases, manual dispatch +# Builds the auto-generated ProperDocs reference site (driven by +# docs/gen_ref_pages.py + properdocs.yml + mkdocstrings) and deploys it to +# https://honeyhiveai.github.io/python-sdk/. Because the reference is +# generated from docstrings in src/honeyhive/, docstring-only changes ship +# as doc changes through this same workflow — no separate generation step. +# +# --strict is intentionally OFF to match the Makefile: there are pre-existing +# griffe / mkdocstrings warnings in the source whose cleanup is tracked as a +# follow-up. Re-add --strict to the build step here once those warnings are +# resolved so doc rot can't accumulate silently. on: push: - branches: [main, complete-refactor] + branches: [federated-sdk-release-candidate] paths: - 'docs/**' - - 'src/**' - - '*.md' + - 'src/honeyhive/**' + - 'properdocs.yml' - 'pyproject.toml' - - '.agent-os/product/**' - - '.agent-os/standards/**' - - 'examples/**' - release: - types: [published] + - 'uv.lock' + - '.github/workflows/docs-deploy.yml' workflow_dispatch: - inputs: - validate_only: - description: 'Only validate, do not deploy' - required: false - default: false - type: boolean permissions: contents: read pages: write id-token: write +# Avoid concurrent deploys stomping on each other; let an in-flight deploy +# finish before starting the next one rather than cancelling it. concurrency: group: "pages-${{ github.ref }}" cancel-in-progress: false jobs: - validate-and-build: - name: Validate and Build Documentation + build: + name: Build site runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v6 - with: - fetch-depth: 0 - - # MANDATORY: AI Assistant Validation Protocol - - name: 🔍 Validate Current API Surface - run: | - echo "AI Assistant Validation Protocol: Checking current API exports..." - - # Verify __init__.py exists and contains expected exports - if [ ! -f "src/honeyhive/__init__.py" ]; then - echo "❌ src/honeyhive/__init__.py not found" - exit 1 - fi - - # Check that HoneyHive and HoneyHiveTracer are in __all__ - if ! grep -q '"HoneyHive"' src/honeyhive/__init__.py; then - echo "❌ HoneyHive not found in __all__ exports" - exit 1 - fi + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - if ! grep -q '"HoneyHiveTracer"' src/honeyhive/__init__.py; then - echo "❌ HoneyHiveTracer not found in __all__ exports" - exit 1 - fi - - echo "✅ API validation passed - both HoneyHive and HoneyHiveTracer found in exports" - - - name: Set up Python 3.11 - uses: actions/setup-python@v6 + - name: Install uv + uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0 with: - python-version: '3.11' - cache: 'pip' - - - name: Create virtual environment (python-sdk) - run: | - python -m venv python-sdk - source python-sdk/bin/activate - echo "python-sdk/bin" >> $GITHUB_PATH - python --version - - - name: Install dependencies - run: | - source python-sdk/bin/activate - python -m pip install --upgrade pip - - # Install package in development mode - pip install -e . - - # Install documentation dependencies - # Pin docutils<0.22 for sphinx-tabs compatibility - pip install sphinx>=7.0.0 sphinx-rtd-theme>=1.3.0 "docutils>=0.20.0,<0.22" - pip install sphinx-autodoc-typehints myst-parser sphinx-copybutton sphinx-design - pip install sphinxcontrib-mermaid sphinx-tabs - - # Validate Sphinx version - python -c "import sphinx; print(f'Sphinx version: {sphinx.__version__}')" - - - name: Test API imports - run: | - source python-sdk/bin/activate - - # Test that our documented API actually works - python -c " - try: - from honeyhive import HoneyHive, HoneyHiveTracer - print('✅ Core imports successful: HoneyHive, HoneyHiveTracer') + enable-cache: true - from honeyhive import trace, evaluate - print('✅ Function imports successful: trace, evaluate') + - name: Build site + run: uv run --extra docs properdocs build - import honeyhive - print(f'✅ Package version: {honeyhive.__version__}') - except ImportError as e: - print(f'❌ Import failed: {e}') - exit(1) - " - - - name: Build Sphinx documentation - run: | - source python-sdk/bin/activate - cd docs - - # Clean previous builds - make clean - - # Build HTML documentation with warnings as errors - echo "🔧 Building documentation with strict validation..." - make html 2>&1 | tee build.log - - # Additional validation: Check for common issues - echo "🔍 Running additional documentation validation..." - # Check for broken internal links (basic validation) - if grep -i "unknown document" build.log; then - echo "❌ Found broken internal links in build log" - cat build.log - exit 1 - fi - - # Check for any warnings that might have been missed - if grep -i "warning" build.log; then - echo "❌ Found warnings in documentation build" - cat build.log - exit 1 - fi - - # Create .nojekyll for GitHub Pages - touch _build/html/.nojekyll - - # Validate build output - if [ ! -f "_build/html/index.html" ]; then - echo "❌ Documentation build failed - index.html not found" - exit 1 - fi - - # Check that key pages exist - required_pages=("tutorials/index.html" "how-to/index.html" "reference/index.html" "development/index.html") - for page in "${required_pages[@]}"; do - if [ ! -f "_build/html/$page" ]; then - echo "❌ Required page missing: $page" - exit 1 - fi - done - - echo "✅ Documentation built and validated successfully" - ls -la _build/html/ - - - name: Upload Pages artifact - if: inputs.validate_only != true - uses: actions/upload-pages-artifact@v4 + - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0 with: - path: ./docs/_build/html + path: site deploy: name: Deploy to GitHub Pages - if: inputs.validate_only != true + needs: build + runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: validate-and-build steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 - - - name: Log deployment success - run: | - echo "✅ Documentation deployed successfully" - echo "📚 URL: ${{ steps.deployment.outputs.page_url }}" + - id: deployment + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml deleted file mode 100644 index 63107fae..00000000 --- a/.github/workflows/docs-preview.yml +++ /dev/null @@ -1,159 +0,0 @@ ---- -name: PR Documentation Preview - -# Build documentation previews for pull requests -# Uploads as artifacts for manual review - -on: - pull_request: - types: [opened, synchronize, reopened] - paths: - - 'docs/**' - - 'src/**' - - '*.md' - - 'pyproject.toml' - - '.github/workflows/docs-*.yml' - - '.agent-os/product/**' - - '.agent-os/standards/**' - - 'examples/**' - -jobs: - validate-api: - name: Validate API Surface - runs-on: ubuntu-latest - steps: - - name: Checkout PR - uses: actions/checkout@v6 - - # MANDATORY: AI Assistant Validation Protocol - - name: 🔍 Validate Current API Surface - run: | - echo "AI Assistant Validation Protocol: Checking current API exports..." - - # Verify core files exist - if [ ! -f "src/honeyhive/__init__.py" ]; then - echo "❌ src/honeyhive/__init__.py not found" - exit 1 - fi - - # Check exports in __all__ (correct way for this codebase) - if ! grep -q '"HoneyHive"' src/honeyhive/__init__.py; then - echo "❌ HoneyHive not found in __all__ exports" - exit 1 - fi - - if ! grep -q '"HoneyHiveTracer"' src/honeyhive/__init__.py; then - echo "❌ HoneyHiveTracer not found in __all__ exports" - exit 1 - fi - - echo "✅ API validation passed" - - build-preview: - name: Build Documentation Preview - runs-on: ubuntu-latest - needs: validate-api - permissions: - pull-requests: write - contents: read - - steps: - - name: Checkout PR - uses: actions/checkout@v6 - - - name: Set up Python 3.11 - uses: actions/setup-python@v6 - with: - python-version: '3.11' - cache: 'pip' - - - name: Create virtual environment (python-sdk) - run: | - python -m venv python-sdk - source python-sdk/bin/activate - echo "python-sdk/bin" >> $GITHUB_PATH - - - name: Install dependencies - run: | - source python-sdk/bin/activate - python -m pip install --upgrade pip - - # Install package - pip install -e . - - # Install documentation dependencies - # Pin docutils<0.22 for sphinx-tabs compatibility - pip install sphinx>=7.0.0 sphinx-rtd-theme>=1.3.0 "docutils>=0.20.0,<0.22" - pip install sphinx-autodoc-typehints myst-parser sphinx-copybutton sphinx-design - pip install sphinxcontrib-mermaid sphinx-tabs - - - name: Test imports - run: | - source python-sdk/bin/activate - - # Verify the API we're documenting actually works - python -c " - from honeyhive import HoneyHive, HoneyHiveTracer - print('✅ Import test passed') - " - - - name: Build documentation - run: | - source python-sdk/bin/activate - cd docs - - # Clean and build - make clean - make html - - # Prepare for web deployment - touch _build/html/.nojekyll - - # Validate output - if [ ! -f "_build/html/index.html" ]; then - echo "❌ Documentation build failed" - exit 1 - fi - - echo "✅ Documentation preview built successfully" - - - name: Upload documentation artifact - uses: actions/upload-artifact@v4 - with: - name: docs-preview-pr-${{ github.event.pull_request.number }} - path: docs/_build/html/ - retention-days: 7 - - - name: Comment PR with preview info - uses: actions/github-script@v7 - with: - script: | - const prNumber = context.issue.number; - const artifactUrl = `${context.serverUrl}/${context.repo.owner}/` + - `${context.repo.repo}/actions/runs/${context.runId}`; - - const body = [ - `📚 Documentation preview built — [Download artifact](${artifactUrl})`, - '', - '
', - 'Review instructions & validation status', - '', - '**How to Review**', - '1. Download the artifact from the link above', - '2. Extract the files', - '3. Open `index.html` in your browser', - '', - '**Validation Status**', - '- API validation: ✅ Passed', - '- Build process: ✅ Successful', - '- Import tests: ✅ All imports working', - '', - '
', - ].join('\n'); - - github.rest.issues.createComment({ - issue_number: prNumber, - owner: context.repo.owner, - repo: context.repo.repo, - body: body - }); diff --git a/.github/workflows/docs-validation.yml b/.github/workflows/docs-validation.yml deleted file mode 100644 index 5f1d8c41..00000000 --- a/.github/workflows/docs-validation.yml +++ /dev/null @@ -1,156 +0,0 @@ ---- -name: Documentation Navigation Validation - -on: - # Run after docs are deployed - MANDATORY on every deploy - workflow_run: - workflows: ["Deploy Documentation"] - types: - - completed - - # Also run on any push to main (docs may be deployed via push) - push: - branches: [main] - paths: - - 'docs/**' - - '.github/workflows/docs-*.yml' - - '.agent-os/product/**' - - '.agent-os/standards/**' - - # Allow manual trigger for testing - workflow_dispatch: - inputs: - base_url: - description: 'Base URL to validate (defaults to production)' - required: false - default: 'https://honeyhiveai.github.io/python-sdk' - - # Weekly monitoring as backup (catch deployment drift) - schedule: - - cron: '0 6 * * 1' # Weekly on Monday at 6 AM UTC - -permissions: - contents: read - actions: read - -jobs: - validate-navigation: - name: Validate Documentation Navigation - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v6 - - - name: Set up Python - uses: actions/setup-python@v6 - with: - python-version: '3.11' - - - name: Install validation dependencies - run: | - pip install -r docs/utils/requirements.txt - - - name: Wait for deployment to complete - if: github.event_name == 'workflow_run' - run: | - echo "🕐 Waiting for deployment to fully complete and propagate..." - echo "📡 GitHub Pages deployment can take up to 10 minutes to fully propagate" - sleep 120 # Wait 2 minutes for immediate availability - - # Check if deployment was successful first - if [ "${{ github.event.workflow_run.conclusion }}" != "success" ]; then - echo "❌ Documentation deployment failed - skipping validation" - exit 0 - fi - - echo "✅ Deployment completed successfully, proceeding with validation" - - - name: Validate production documentation - if: github.event_name != 'workflow_dispatch' - run: | - python docs/utils/validate_navigation.py \ - --base-url https://honeyhiveai.github.io/python-sdk \ - --timeout 15 - - - name: Validate custom URL documentation - if: github.event_name == 'workflow_dispatch' - run: | - python docs/utils/validate_navigation.py \ - --base-url "${{ github.event.inputs.base_url }}" \ - --timeout 15 - - - name: Report results - if: failure() - run: | - echo "🚨 CRITICAL: Documentation navigation validation failed!" - echo "📋 This indicates broken documentation that affects users" - echo "🔍 Check the logs above for specific broken links or missing pages" - echo "" - echo "💡 Common issues and fixes:" - echo " - New pages not added to toctree → Add to appropriate index.rst" - echo " - Broken cross-references → Fix :doc: or :ref: targets" - echo " - Missing files after restructuring → Update all references" - echo " - Deployment issues → Check GitHub Pages configuration" - echo "" - echo "🛠️ To fix locally:" - echo " 1. python docs/utils/validate_navigation.py --local" - echo " 2. Fix any reported issues" - echo " 3. Test with: tox -e docs" - echo " 4. Commit and push fixes" - echo "" - echo "⚠️ Documentation deployment is considered FAILED until navigation works" - exit 1 - - validate-local-build: - name: Validate Local Documentation Build - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v6 - - - name: Set up Python - uses: actions/setup-python@v6 - with: - python-version: '3.11' - - - name: Install dependencies - run: | - pip install -e . - pip install -r docs/utils/requirements.txt - pip install restructuredtext-lint rstcheck-core doc8 - - - name: Build documentation locally - run: | - cd docs - python -m http.server 8000 --directory _build/html & - SERVER_PID=$! - echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV - sleep 5 - env: - SPHINX_BUILD_WARNINGS: true - - - name: Run tox docs build - run: | - tox -e docs - - - name: Documentation Quality Check - run: | - python scripts/docs-quality.py check --path docs - - - name: Validate local build navigation - run: | - cd docs - python -m http.server 8000 --directory _build/html & - SERVER_PID=$! - sleep 10 - python utils/validate_navigation.py --local --timeout 10 - kill $SERVER_PID - - - name: Cleanup - if: always() - run: | - if [ ! -z "$SERVER_PID" ]; then - kill $SERVER_PID || true - fi diff --git a/.github/workflows/docs-versioned.yml b/.github/workflows/docs-versioned.yml deleted file mode 100644 index 97106f99..00000000 --- a/.github/workflows/docs-versioned.yml +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: Deploy Versioned Documentation - -# Manage versioned documentation using mike -# Creates separate versions for different releases and branches - -on: - push: - branches: [main] - tags: - - 'v*' - workflow_dispatch: - inputs: - version: - description: 'Version to deploy (e.g., 0.1.0, latest, dev)' - required: true - default: 'dev' - alias: - description: 'Alias for this version (e.g., latest, stable)' - required: false - -permissions: - contents: write - pages: write - id-token: write - -jobs: - deploy-versioned-docs: - name: Deploy Versioned Documentation - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v6 - with: - fetch-depth: 0 # Full history needed for mike versioning - - - name: Configure Git - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - - # MANDATORY: AI Assistant Validation Protocol - - name: 🔍 Validate Current API Surface - run: | - echo "AI Assistant Validation Protocol: Checking current API exports..." - - # Verify __init__.py exists and contains expected exports - if [ ! -f "src/honeyhive/__init__.py" ]; then - echo "❌ src/honeyhive/__init__.py not found" - exit 1 - fi - - # Check that HoneyHive and HoneyHiveTracer are in __all__ - if ! grep -q '"HoneyHive"' src/honeyhive/__init__.py; then - echo "❌ HoneyHive not found in __all__ exports" - exit 1 - fi - - if ! grep -q '"HoneyHiveTracer"' src/honeyhive/__init__.py; then - echo "❌ HoneyHiveTracer not found in __all__ exports" - exit 1 - fi - - echo "✅ API validation passed" - - - name: Set up Python 3.11 - uses: actions/setup-python@v6 - with: - python-version: '3.11' - cache: 'pip' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - - # Install package - pip install -e . - - # Install documentation and versioning tools - pip install mike>=2.0.0 - pip install sphinx>=7.0.0 sphinx-rtd-theme>=1.3.0 - pip install sphinx-autodoc-typehints myst-parser sphinx-copybutton sphinx-design - pip install sphinxcontrib-mermaid sphinx-tabs - - - name: Test imports before versioning - run: | - # Ensure our API is working before we document it - python -c " - from honeyhive import HoneyHive, HoneyHiveTracer - import honeyhive - print(f'✅ API working, version: {honeyhive.__version__}') - " - - - name: Determine version and alias - id: version - run: | - if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then - VERSION="${{ github.event.inputs.version }}" - ALIAS="${{ github.event.inputs.alias }}" - elif [[ "${{ github.ref }}" == refs/tags/v* ]]; then - VERSION="${GITHUB_REF#refs/tags/v}" - ALIAS="stable" - elif [[ "${{ github.ref }}" == "refs/heads/main" ]]; then - VERSION="dev" - ALIAS="latest" - else - VERSION="dev" - ALIAS="" - fi - - echo "version=$VERSION" >> $GITHUB_OUTPUT - echo "alias=$ALIAS" >> $GITHUB_OUTPUT - echo "📝 Deploying version: $VERSION with alias: $ALIAS" - - - name: Build and deploy with mike - run: | - cd docs - - # Build the documentation - make clean - make html - - VERSION="${{ steps.version.outputs.version }}" - ALIAS="${{ steps.version.outputs.alias }}" - - # Initialize mike if this is the first run - if ! git ls-remote --heads origin gh-pages | grep -q gh-pages; then - echo "📝 Initializing mike for first-time versioned docs" - mike deploy --push --update-aliases "$VERSION" "$ALIAS" || true - fi - - # Deploy the version - if [ -n "$ALIAS" ]; then - mike deploy --push --update-aliases "$VERSION" "$ALIAS" - echo "✅ Deployed version $VERSION with alias $ALIAS" - else - mike deploy --push "$VERSION" - echo "✅ Deployed version $VERSION" - fi - - # Set default version to latest - if [ "$ALIAS" = "latest" ]; then - mike set-default --push latest - echo "✅ Set 'latest' as default version" - fi - - - name: Show deployed versions - run: | - cd docs - echo "📚 Available documentation versions:" - mike list