finit/.github/workflows/docs.yml

name: Dotty the Documenteer

on:
  push:
    branches:
      - master
      - 4.x
    paths:
      - 'doc/**'
      - 'README.md'
      - 'mkdocs.yml'
      - 'configure.ac'
      - '.github/workflows/docs.yml'
  pull_request:
    types: [opened, synchronize, reopened, labeled]
    paths:
      - 'doc/**'
      - 'README.md'
      - 'mkdocs.yml'
      - 'configure.ac'
      - '.github/workflows/docs.yml'

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Needed for git-revision-date-localized plugin

      - name: Determine docs version
        id: version
        run: |
          version=$(sed -n 's/^AC_INIT(\[Finit\], *\[\([0-9]*\)\..*/\1.x/p' configure.ac)
          test -n "$version"
          echo "version=$version" >> $GITHUB_OUTPUT

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install dependencies
        run: |
          pipx install mkdocs
          pipx inject mkdocs mkdocs-material
          pipx inject mkdocs pymdown-extensions
          pipx inject mkdocs mkdocs-callouts
          pipx inject mkdocs mkdocs-glightbox

      - name: Build documentation
        run: mkdocs build --clean

      - name: Upload site artifact
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: site/

  deploy:
    if: github.event_name == 'push'
    needs: build
    runs-on: ubuntu-latest
    env:
      VERSION: ${{ needs.build.outputs.version }}

    steps:
      - name: Download site artifact
        uses: actions/download-artifact@v4
        with:
          name: site
          path: site/

      - name: Checkout pages repo
        uses: actions/checkout@v4
        with:
          repository: finit-project/finit-project.github.io
          path: pages
          ssh-key: ${{ secrets.DOCS_DEPLOY_KEY }}
          persist-credentials: true

      - name: Setup SSH for push
        run: |
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          ssh-keyscan github.com >> ~/.ssh/known_hosts

      - name: Sync site to pages repo
        run: |
          rsync -a --delete site/ "pages/$VERSION/"

      - name: Update version index and redirects
        run: |
          cd pages/

          # The root holds only version directories and the files
          # generated below, drop anything else (pre-versioned site)
          find . -maxdepth 1 ! -name . ! -name .git ! -name CNAME \
               ! -name '[0-9]*.x' -exec rm -rf {} +

          latest=$(ls -d [0-9]*.x | sort -rV | head -1)

          sep=
          printf '[' > versions.json
          for v in $(ls -d [0-9]*.x | sort -rV); do
              printf '%s{"version": "%s", "title": "%s", "aliases": []}' \
                     "$sep" "$v" "$v" >> versions.json
              sep=', '
          done
          printf ']\n' >> versions.json

          cat > index.html <<EOF
          <!DOCTYPE html>
          <html>
            <head>
              <meta charset="utf-8">
              <meta http-equiv="refresh" content="0; url=$latest/">
              <link rel="canonical" href="https://finit-project.github.io/$latest/">
            </head>
          </html>
          EOF

          cat > 404.html <<EOF
          <!DOCTYPE html>
          <html>
            <head>
              <meta charset="utf-8">
              <title>Finit &mdash; page not found</title>
              <script>
                var path = window.location.pathname;
                if (!/^\/[0-9]+\.x(\/|$)/.test(path))
                  window.location.replace("/$latest" + path);
              </script>
            </head>
            <body>
              <p>Page not found.  Try the <a href="/$latest/">latest User Guide</a>.</p>
            </body>
          </html>
          EOF

      - name: Commit and push
        run: |
          cd pages/
          if [ -z "$(git status --porcelain)" ]; then
              exit 0
          fi

          SRC_REPO="${GITHUB_REPOSITORY}"
          SRC_REF="${GITHUB_SHA::7}"
          SRC_URL="https://github.com/${SRC_REPO}/commit/${SRC_REF}"

          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add -A
          git commit -m "docs: update from ${SRC_REPO}@${SRC_REF}" \
                     -m "For details, see ${SRC_URL}"
          git push