docs.yml

name: Documentation
# Deploy sphinx documentation to GitHub Pages in docs branch

on:
    # Triggers the workflow on push or pull request events but only for the "main" branch
    push:
        branches: [ "main" ]
    pull_request:

jobs:
    build:
        runs-on: ubuntu-24.04
        steps:
            # Checkout the repository
            - name: Checkout repository
              uses: actions/checkout@v2
            # Set up ROS
            - name: Set up ROS
              uses: ros-tooling/setup-ros@v0.7
              with:
                required-ros-distributions: jazzy
            # Update pip
            - name: Update pip
              run: python -m pip install --break-system-packages --upgrade pip
            # Install packages
            - name: Install our package
              run: |
                    source /opt/ros/jazzy/setup.bash
                    python -m pip install --break-system-packages .
            # Install the docs dependencies (sphinx)
            - name: Install dependencies
              run: python -m pip install --break-system-packages -r docs/requirements.txt
            # build the documentation
            - name: Build documentation
              run: |
                    source /opt/ros/jazzy/setup.bash
                    cd docs
                    make html
            # upload the documentation to GitHub Pages
            - name: Upload artifact
              uses: actions/upload-pages-artifact@v3
              with:
                    path: docs/build/html
              if: github.ref == 'refs/heads/main'
    deploy:
        # Add a dependency to the build job
        needs: build

        # Only deploy from main
        if: github.ref == 'refs/heads/main'

        # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
        permissions:
            pages: write      # to deploy to Pages
            id-token: write   # to verify the deployment originates from an appropriate source

        # Deploy to the github-pages environment
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}

        runs-on: ubuntu-latest

        steps:
            # deploy the documentation to GitHub Pages
            - name: Deploy to github pages
              id: deployment
              uses: actions/deploy-pages@v4