documentation.yaml

name: pypop.org website and docs generation

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

on:
  workflow_dispatch:
  push:
    paths:
      - '*.rst'
      - 'NEWS.md'
      - 'LICENSE'
      - 'website/**'
      - 'tests/data/doc-examples/**'
      - 'src/PyPop/CommandLineInterface.py'
      - '.github/workflows/documentation.yaml'
      - '!website/README.md'
      - '!website/reference/**'
  pull_request:
    paths:
      - '*.rst'
      - 'NEWS.md'
      - 'LICENSE'
      - 'website/**'
      - 'tests/data/doc-examples/**'
      - 'src/PyPop/CommandLineInterface.py'
      - '.github/workflows/documentation.yaml'
      - '!website/README.md'
      - '!website/reference/**'
  release:
    types:
      - published


permissions:
  contents: write
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check GitHub Action permissions
        run: |
          echo "github.actor:  ${{ toJson(github.actor) }}"
          echo "github.triggering_actor:  ${{ toJson(github.triggering_actor) }}"
          echo "github.repository_owner:  ${{ toJson(github.repository_owner) }}"
          echo "github.repository_owner:  ${{ toJson(github.repository_owner) }}"
          echo "github.repository: ${{ toJson(github.repository) }}"
          echo "github.event.pull_request.base.repo.full_name: ${{ toJson(github.event.pull_request.base.repo.full_name) }}"
          echo "github.event.pull_request.head.repo.full_name: ${{ toJson(github.event.pull_request.head.repo.full_name) }}"
          echo "github.ref: ${{ toJson(github.ref) }}"
          echo "github.event_name: ${{ toJson(github.event_name) }}"
          echo "github.event.action: ${{ toJson(github.event.action) }}"
          echo "github.event.release.target_commitish: ${{ toJson(github.event.release.target_commitish) }}"

      - uses: actions/setup-python@v5
      - name: Install dependencies
        run: |
          pip install setuptools_scm sphinx==7.2.5 piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse sphinx_copybutton sphinxcontrib-bibtex
          sudo apt clean
          sudo apt-get update
          sudo apt-get install --fix-missing -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-luatex texlive-xetex
      - name: Sphinx build
        run: |
          # latex build in separate directory
          # it generates a lot of files we don't need to keep
          sphinx-build -b latex website _latexbuild
          make -C _latexbuild
          # create _build directory and move the PDF there
          mkdir _build
          cp _latexbuild/*.pdf _build/
          # now build the HTML
          sphinx-build website _build

      - name: Deploy to beta site
        uses: peaceiris/actions-gh-pages@v3
        # only update beta site if base and head branches match, not for forks
        # forks cannot access secrets to deploy, see: https://github.com/orgs/community/discussions/26829
        if: ${{ (github.event.pull_request.base.repo.full_name == github.event.pull_request.head.repo.full_name) }}
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: alexlancaster/beta.pypop.org
          publish_branch: gh-pages  # default: gh-pages
          publish_dir: _build/
          force_orphan: true

      - name: Deploy to production
        uses: peaceiris/actions-gh-pages@v3
        # only update on either a push on main, or published release on the main
        if: ${{ (github.ref == 'refs/heads/main' && github.event_name == 'push') || (github.event.release.target_commitish == 'main' && github.event_name == 'release' && github.event.action == 'published') }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/
          force_orphan: true