documentation.yml

name: documentation
on:
  # Triggers the workflow on push but only for the main branch
  push:
    branches: [ main ]
    tags: [ v* ]
    paths:
      - src/specsanalyzer/**/*
      - src/specsscan/**/*
      - tutorial/**
      - .github/workflows/documentation.yml
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

env:
  UV_SYSTEM_PYTHON: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Check out repo and set up Python
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # see https://stackoverflow.com/questions/57612428/cloning-private-github-repository-within-organisation-in-actions and https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key
      - name: Fetch test data
        run: |
          eval `ssh-agent -s`
          ssh-add - <<< '${{ secrets.TEST_DATA_ACCESS_KEY }}'
          git submodule sync --recursive
          git submodule update --init --recursive --jobs=4

      # Setup python
      - name: Set up Python 3.10
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Install dependencies
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Install package
        run: |
          uv pip install ".[docs,notebook]"

      - name: Install pandoc
        run: |
          sudo wget https://github.com/jgm/pandoc/releases/download/3.1.8/pandoc-3.1.8-1-amd64.deb
          sudo dpkg -i pandoc-3.1.8-1-amd64.deb

      - name: copy tutorial files to docs
        run: |
          cp -r $GITHUB_WORKSPACE/tutorial $GITHUB_WORKSPACE/docs/
          mkdir $GITHUB_WORKSPACE/docs/tests
          cp -r $GITHUB_WORKSPACE/tests/data $GITHUB_WORKSPACE/docs/tests/
          mkdir -p $GITHUB_WORKSPACE/docs/src/specsscan
          cp -r $GITHUB_WORKSPACE/src/specsscan/config $GITHUB_WORKSPACE/docs/src/specsscan

      - name: build Sphinx docs
        run: sphinx-build -b html $GITHUB_WORKSPACE/docs $GITHUB_WORKSPACE/_build

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: sphinx-docs
          path: _build

  # this job pushes the built documentation to the docs repository
  push:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v4
        with:
          repository: ${{ github.repository_owner }}/docs
          token: ${{ secrets.GITHUB_TOKEN }}
          path: 'docs-repo'

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.SSH_DOCS_DEPLOY_KEY }}

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: sphinx-docs
          path: sphinx-docs

      - name: Determine version folder
        id: version-folder
        run: |
          if [[ $GITHUB_REF == refs/tags/* ]]; then
            VERSION=${GITHUB_REF#refs/tags/}
            echo "folder=specsanalyzer/$VERSION" >> $GITHUB_OUTPUT
            if [[ $VERSION == *a* ]]; then
              rm -rf docs-repo/specsanalyzer/latest
              ln -s -r docs-repo/specsanalyzer/$VERSION docs-repo/specsanalyzer/latest
            else
              rm -rf docs-repo/specsanalyzer/stable
              rm -rf docs-repo/specsanalyzer/latest
              ln -s -r docs-repo/specsanalyzer/$VERSION docs-repo/specsanalyzer/stable
              ln -s -r docs-repo/specsanalyzer/$VERSION docs-repo/specsanalyzer/latest
            fi
          elif [[ $GITHUB_REF == refs/heads/main ]]; then
            rm -rf docs-repo/specsanalyzer/latest
            echo "folder=specsanalyzer/latest" >> $GITHUB_OUTPUT
          else
            rm -rf docs-repo/specsanalyzer/develop
            echo "folder=specsanalyzer/develop" >> $GITHUB_OUTPUT
          fi

      - name: Update switcher.json
        run: |
          VERSION=`grep "<title>" sphinx-docs/index.html | sed -n 's/.*specsanalyzer \(.*\) documentation.*/\1/p'`
          echo "python docs-repo/specsanalyzer/update_switcher.py docs-repo/specsanalyzer/switcher.json $GITHUB_REF $VERSION"
          python docs-repo/specsanalyzer/update_switcher.py docs-repo/specsanalyzer/switcher.json $GITHUB_REF $VERSION

      - name: Copy documentation to the right version folder
        run: |
          mkdir -p docs-repo/${{ steps.version-folder.outputs.folder }}
          cp -r sphinx-docs/* docs-repo/${{ steps.version-folder.outputs.folder }}
          rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/.doctrees
          rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/tutorial/*.ipynb

      - name: Push changes
        run: |
          cd docs-repo
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add .
          git commit -m "Update documentation"
          git push