generate_doc.yml

name: Generate documentation

on:
  push:
    branches:
      - main
    tags:
      - v*.*.*
  pull_request:

jobs:
  build-doc:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: "3.x"


    - name: Differentiate main from tag
      run: |
        if [ "${{ github.ref_name }}" != "main" ] ; then
          echo "new_tag=1" >> "$GITHUB_ENV"
        else
          echo "new_tag=0" >> "$GITHUB_ENV"
        fi

    - name: Install pip packages
      working-directory: docs
      run: |
        pip install pip --upgrade
        pip install -r requirements.txt

    - name: Generate test report files
      working-directory: docs
      run: |
        python3 test_report_generator.py . ../testing_results/

    - name: Build doc
      working-directory: docs
      run: |
        python3 extract_macros.py ../ user_guide/preferences_table.rst
        export ADOC_DOC_VERSION=${{ github.ref_name }}
        make html SPHINXOPTS='-W --keep-going'

    - name: Store the generated doc
      uses: actions/upload-artifact@v4
      with:
        name: html
        path: docs/_build/html

  deploy-doc:
    runs-on: ubuntu-latest
    needs: build-doc
    if: startsWith(github.ref, 'refs/tags/') ||  github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v4
    - run: |
        git config --global user.name "${{ github.event.head_commit.committer.name }}"
        git config --global user.email "${{ github.event.head_commit.committer.email }}"

    - name: Create gh-pages branch
      run: >
        git reset --hard ;
        git clean -fdx ;
        git ls-remote --exit-code --heads origin refs/heads/gh-pages &&
        (
          git fetch origin gh-pages ;
          git checkout -b gh-pages origin/gh-pages ;
          DOC_BUILDS=$(find . -mindepth 2 -name objects.inv -exec sh -c 'dirname {}' ';') ;
          git rm -r . --quiet || true ;
          printf "Detected doc builds: $DOC_BUILDS" ;
          if ! [ -z "$DOC_BUILDS" ]; then
            git checkout @ -- $DOC_BUILDS ;
          fi ;
          if [[ "$new_tag" == "1" ]]; then
            git rm -r ${{ github.ref_name }} --quiet || true ;
          fi ;
        ) || (
          git checkout --orphan gh-pages ;
          git reset --hard ;
          git commit -m "initial commit" --allow-empty
        )

    - uses: actions/download-artifact@v4
      if: ${{ env.new_tag == '0' }}
      with:
        name: html

    - uses: actions/download-artifact@v4
      if: ${{ env.new_tag == '1' }}
      with:
        name: html
        path: ${{ github.ref_name }}

    - name: Generate aux files
      run: |
        touch .nojekyll ;
        find . -name objects.inv -exec sh -c 'dirname {}' ';' |
        cut -c 3- | sort -r |
        jq --raw-input . |
        jq --slurp . > tags.json

    - name: Commit and push to gh-pages
      run: |
        git add . >> /dev/null
        git commit -m "deploy: ${GITHUB_SHA}" --allow-empty
        git push origin gh-pages:gh-pages