This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Deploy Documentation to GitHub Pages | |
| on: | |
| push: | |
| branches: [ main, master ] # Deploy when pushing to main/master branch | |
| pull_request: | |
| branches: [ main, master ] # Also build on PRs to test | |
| workflow_dispatch: # Allow manual triggering | |
| # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| # Build job | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # Fetch all history for proper versioning | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' # Match your project's Python version | |
| cache: 'pip' | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| # Install basic requirements first | |
| pip install sphinx>=7.0 myst-parser furo nbsphinx sphinx-autobuild | |
| # Then install project | |
| pip install -e .[docs] || pip install -e . | |
| - name: Verify installation | |
| run: | | |
| python -c "import sphinx; print(f'Sphinx version: {sphinx.__version__}')" | |
| python -c "import myst_parser; print(f'MyST parser version: {myst_parser.__version__}')" | |
| which sphinx-build | |
| - name: Sync notebooks from root | |
| run: | | |
| mkdir -p docs/source/notebooks | |
| cp notebooks/Store_explorer.ipynb docs/source/notebooks/ 2>/dev/null || echo "Store_explorer.ipynb not found, skipping..." | |
| cp notebooks/Visuals_BC.ipynb docs/source/notebooks/ 2>/dev/null || echo "Visuals_BC.ipynb not found, skipping..." | |
| cp notebooks/RESources_report_builder.ipynb docs/source/notebooks/ 2>/dev/null || echo "RESources_report_builder.ipynb not found, skipping..." | |
| cp notebooks/Visuals.ipynb docs/source/notebooks/ 2>/dev/null || echo "Visuals.ipynb not found, skipping..." | |
| echo "Notebooks synced successfully!" | |
| - name: Setup Pages | |
| id: pages | |
| uses: actions/configure-pages@v4 | |
| - name: Build documentation with Sphinx | |
| run: | | |
| echo "Building documentation with sphinx-build..." | |
| echo "Current directory: $(pwd)" | |
| echo "Source dir exists: $(test -d docs/source && echo 'YES' || echo 'NO')" | |
| echo "Config file exists: $(test -f docs/source/conf.py && echo 'YES' || echo 'NO')" | |
| # Test conf.py | |
| cd docs/source && python -c "import conf; print('conf.py imported successfully')" || echo "conf.py import failed" | |
| cd ../.. | |
| # Build documentation | |
| mkdir -p docs/build/html | |
| sphinx-build -v -b html docs/source docs/build/html | |
| # Add .nojekyll file to disable Jekyll processing | |
| touch docs/build/html/.nojekyll | |
| echo "Documentation built successfully!" | |
| echo "Generated files:" | |
| ls -la docs/build/html/ # List generated files for debugging | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs/build/html | |
| # Deploy job | |
| deploy: | |
| if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' # Only deploy from main/master | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| needs: build | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |