This file contains 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: Build and Deploy Documentation to GitHub Pages | |
| on: | |
| push: | |
| branches: ["main"] # Trigger the build on pushes to the main branch | |
| workflow_dispatch: # Allow manual triggers from the GitHub Actions tab | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| deploy: | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| # Step 1: Checkout the repository | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # Fetch all history for reliable change detection | |
| # Step 2: Check for changes in the docs-source directory | |
| - name: Check for changes in docs-source | |
| id: changes-check | |
| run: | | |
| if git diff --quiet ${{ github.event.before }} ${{ github.sha }} -- docs-source; then | |
| echo "changes-detected=false" >> $GITHUB_ENV | |
| echo "No changes detected in docs-source" | |
| else | |
| echo "changes-detected=true" >> $GITHUB_ENV | |
| echo "Changes detected in docs-source" | |
| fi | |
| shell: bash | |
| # Step 3: Set up Python (only if changes are detected) | |
| - name: Set up Python | |
| uses: actions/setup-python@v3 | |
| with: | |
| python-version: 3.9 | |
| if: env.changes-detected == 'true' | |
| # Step 4: Install dependencies | |
| - name: Install dependencies | |
| if: env.changes-detected == 'true' | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs-source/requirements.txt | |
| # Step 5: Build the documentation | |
| - name: Build documentation | |
| if: env.changes-detected == 'true' | |
| run: | | |
| cd docs-source # Navigate to the docs-source directory | |
| make clean # Clean any previous build files | |
| make html # Generate the HTML documentation | |
| # Step 6: Prepare the docs for deployment | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v5 | |
| if: env.changes-detected == 'true' | |
| # Step 7: Upload the built HTML files as an artifact | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs-source/_build/html # Upload the built HTML files | |
| if: env.changes-detected == 'true' | |
| # Step 8: Deploy the built docs to GitHub Pages | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| if: env.changes-detected == 'true' |