build-docs.yml

name: Build Docs

on:
  - push
  - pull_request
  # You can manually run this workflow.
  - workflow_dispatch

# Improve CI concurrency by automatically cancelling outdated jobs.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: write # to push to gh-pages branch

jobs:

# ---------------------------------------------------------------------------------------

  build:

# ---------------------------------------------------------------------------------------

    runs-on: ubuntu-latest

    steps:
      - name: 🤘 Checkout Code
        uses: actions/checkout@v6 # https://github.com/actions/checkout

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            build-essential \
            graphviz \
            default-jre-headless \
            ruby \
            ruby-dev

      - name: Install Ruby gems
        run: |
          gem install --user-install \
            asciidoctor \
            asciidoctor-diagram \
            rouge
          echo "PATH=$HOME/.local/share/gem/ruby/3.2.0/bin:$PATH" >> $GITHUB_ENV

      - name: Copy images
        run: |
          mkdir -p user-manual/images
          cp -p images/* user-manual/images/

      - name: Build HTML documentation
        env:
          REVNUMBER: ${{ github.sha }}
        run: |
          echo "Building user-manual..."
          asciidoctor \
            -a icons=font \
            -a source-highlighter=rouge \
            -a toc=left \
            -a toclevels=3 \
            -a revnumber=$REVNUMBER \
            user-manual/en/book.adoc \
            -o user-manual/en/index.html

          echo "Building developer-manual..."
          asciidoctor \
            -r asciidoctor-diagram \
            -a icons=font \
            -a source-highlighter=rouge \
            -a toc=left \
            -a toclevels=3 \
            -a revnumber=$REVNUMBER \
            developer-manual/en/book.adoc \
            -o developer-manual/en/index.html

          echo "Building FAQ..."
          asciidoctor \
            -a icons=font \
            -a source-highlighter=rouge \
            -a revnumber=$REVNUMBER \
            faq/faq.adoc \
            -o faq/index.html

          echo "Building index..."
          asciidoctor README.adoc -o index.html

      # - name: Build PDF documentation
      #   env:
      #     REVNUMBER: ${{ github.sha }}
      #   run: |
      #     asciidoctor -r asciidoctor-pdf -b pdf \
      #       -a pdf-stylesdir=pdf -a pdf-style=fife \
      #       -a pdf-fontsdir=pdf/fonts \
      #       -a revnumber=$REVNUMBER \
      #       user-manual/en/book.adoc -o user-manual/en/book.pdf
      #
      #     asciidoctor -r asciidoctor-diagram -r asciidoctor-pdf -b pdf \
      #       -a pdf-stylesdir=pdf -a pdf-style=fife \
      #       -a pdf-fontsdir=pdf/fonts \
      #       -a revnumber=$REVNUMBER \
      #     developer-manual/en/book.adoc -o developer-manual/en/book.pdf

      - name: Remove source files
        run: |
          find . -name '*.adoc' -type f -delete

      # Push to gh-pages branch. This parts needs permissions contents: write.
      - name: Push to gh-pages
        if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
        run: |
          echo "Tell git who we are"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git config --global user.name "github-actions[bot]"
          git fetch origin
          echo "checkout gh-pages branch without history (orphan)"
          git checkout --orphan gh-pages
          echo "remove all asciidoc (.adoc) source files"
          git ls-files | grep '\.adoc$' | xargs git rm --cached || true
          echo "remove unnecessary files"
          git rm -f .gitattributes
          git rm -rf .github/
          echo "add & commit everything new"
          git add --all
          git commit -m "Updated Documentation. [skip ci]" || true
          git push origin gh-pages --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # This step is only required, when using the deploy step below.
      # Requires setting: Settings → Pages → Source: GitHub Actions
      # - name: Upload documentation artifact
      #   uses: actions/upload-pages-artifact@v4 # https://github.com/actions/upload-pages-artifact
      #   with:
      #     path: ./

# # ---------------------------------------------------------------------------------------

#   deploy:

# # ---------------------------------------------------------------------------------------

#     needs: build
#     if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'

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

#     runs-on: ubuntu-latest

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

#     steps:
#       - name: Setup GitHub Pages
#         uses: actions/configure-pages@v5 # https://github.com/actions/configure-pages

#       - name: Deploy to GitHub Pages
#         id: deployment
#         uses: actions/deploy-pages@v4 # https://github.com/actions/deploy-pages