documentation.yaml

# From: https://github.com/rkdarst/sphinx-actions-test/blob/master/.github/workflows/sphinx-build.yml
name: Sphinx

on: [push, pull_request, workflow_dispatch]

# If these SPHINXOPTS are enabled, then be strict about the builds and
# fail on any warnings
#env:
#  SPHINXOPTS: "-W --keep-going -T"


jobs:
  Build:
    name: Build and gh-pages
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      # https://github.com/marketplace/actions/checkout
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          lfs: true

      - name: Install drawio
        run: |
          sudo apt-get update
          sudo apt-get -y install wget curl
          curl -s https://api.github.com/repos/jgraph/drawio-desktop/releases/latest | grep browser_download_url | grep `dpkg --print-architecture` | grep '\.deb' | cut -d '"' -f 4 | wget -i -
          sudo apt-get -f install ./drawio-amd64-*.deb

      # https://github.com/marketplace/actions/setup-python
      # ^-- This gives info on matrix testing.
      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: '>=3.10' 

      # https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies
      # ^-- How to set up caching for pip on Ubuntu
      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-
            ${{ runner.os }}-

      # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
      # ^-- This gives info on installing dependencies with pip
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -U -r requirements.txt

      - name: Debugging information
        run: |
          echo "github.ref:" ${{github.ref}}
          echo "github.event_name:" ${{github.event_name}}
          echo "github.head_ref:" ${{github.head_ref}}
          echo "github.base_ref:" ${{github.base_ref}}
          git rev-parse --abbrev-ref HEAD
          git branch
          git branch -a
          git remote -v

      - name: List installed python packages
        run: |
          pip list

      - name: Setup TeX Live
        uses: teatimeguest/setup-texlive-action@v3
        with:
          packages: >-
            collection-latexextra
            tex-gyre
          # anyfontsize
          # latexmk
          # dvisvgm
          # cmap
          # fncychap
          # float
    
      # Build
      - uses: ammaraskar/sphinx-problem-matcher@master
      - name: Build Sphinx docs
        run: |
          make dirhtml

      # - name: Generate PDF 1
      #   run: |
      #     pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
      #     make pyppeteer
      #     mv _build/pyppeteer/*.pdf _build/dirhtml/_static/Manuel_1.pdf

      - name: Generate PDF 1
        run: |
          pip install sphinx_pyppeteer_builder
          make pyppeteer
          mv _build/pyppeteer/*.pdf _build/dirhtml/_static/Manuel_1.pdf

      - name: Generate PDF 2
        run: |
          make simplepdf
          mv _build/simplepdf/*.pdf _build/dirhtml/_static/Manuel_2.pdf

      # - name: Generate PDF 3
      #   run: |
      #     make latexpdf
      #     mv _build/latex/*.pdf _build/dirhtml/_static/Manuel_3.pdf

      - uses: actions/upload-artifact@v4
        with:
          name: my-artifact
          path: _build

  # The following supports building all branches and combining on
  # gh-pages

  # Clone and set up the old gh-pages branch
  Update_gh-pages:
    name: Update gh-pages
    runs-on: ubuntu-latest
    needs: [Build]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          lfs: true

      - uses: actions/download-artifact@v4
        with:
          name: my-artifact
          path: _build

      # https://github.com/marketplace/actions/checkout
      - name: Clone old gh-pages
        if: ${{ github.event_name == 'push' }}
        run: |
          set -x
          git fetch
          ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
          rm -rf _gh-pages/.git/
          mkdir -p _gh-pages/branch/
      # If a push and main, copy build to _gh-pages/ as the "main"
      # deployment.
      - name: Copy new build (main)
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        run: |
          set -x
          # Delete everything under _gh-pages/ that is from the
          # primary branch deployment.  Eicludes the other branches
          # _gh-pages/branch-* paths, and not including
          # _gh-pages itself.
          find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
          rsync -a _build/dirhtml/ _gh-pages/
      # If a push and not on main, then copy the build to
      # _gh-pages/branch/$brname (transforming '/' into '--')
      - name: Copy new build (branch)
        if: ${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
        run: |
          set -x
          #brname=$(git rev-parse --abbrev-ref HEAD)
          brname="${{github.ref}}"
          brname="${brname##refs/heads/}"
          brdir=${brname//\//--}   # replace '/' with '--'
          rm -rf   _gh-pages/branch/${brdir}
          rsync -a _build/dirhtml/ _gh-pages/branch/${brdir}
      # Go through each branch in _gh-pages/branch/, if it's not a
      # ref, then delete it.
      - name: Delete old feature branches
        if: ${{ github.event_name == 'push' }}
        run: |
          set -x
          for brdir in `ls _gh-pages/branch/` ; do
              brname=${brdir//--/\/}   # replace '--' with '/'
              if ! git show-ref remotes/origin/$brname ; then
                  echo "Removing $brdir"
                  rm -r _gh-pages/branch/$brdir/
              fi
          done

      - uses: actions/upload-artifact@v4
        with:
          name: gh-pages-artifact
          path: _gh-pages

  # Deploy
  # https://github.com/peaceiris/actions-gh-pages                    
  Deploy:
    runs-on: ubuntu-latest
    needs: [Update_gh-pages]
    if: ${{ github.ref == 'refs/heads/main' }}
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: gh-pages-artifact
          path: _gh-pages
          
      - name: Deploy gh-pages
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' }}
        #if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _gh-pages/
          force_orphan: true