docs.yml

name: Documentation

on:
  push:
    branches: [main]
    tags: ["*"]
  pull_request:
    # Check all PR
  schedule:
    - cron: '0 8 * * 1' # run every Monday at 8am UTC

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      examplesmatrix: ${{ steps.gatherInfo.outputs.examplesjson }}
      latest_docs_run: ${{ steps.gatherInfo.outputs.latest_docs_run }}
    permissions: read-all # Permissions for the GITHUB_TOKEN
    steps:
      - uses: actions/checkout@v6
        with:
          # The checkout by default doesn't fetch any history, but for PR
          # we want to check which files have been modified.
          # The action actions/checkout@v6 squashes the history of the PR,
          # into a single commit so we need to fetch with a depth of 2.
          fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}

      - id: gatherInfo
        # Collect the examples that need to be run, and the id of the latest
        # workflow run on the main branch.
        run: |
          GET_EXAMPLES_ARGS=""
          if ${{ github.event_name == 'pull_request' }}; then
            GET_EXAMPLES_ARGS=" --modified-files $(git diff --name-only -r HEAD^1 HEAD)"
          fi
          echo examplesjson=$(./src/get_examples.py ${GET_EXAMPLES_ARGS}) >> $GITHUB_OUTPUT
          echo latest_docs_run=$(./src/latest_docs_run.py id --api-token ${{ secrets.GITHUB_TOKEN }}) >> $GITHUB_OUTPUT

  generate-example:
    needs: setup
    runs-on: ubuntu-latest
    # Handle the case where there are no examples to run.
    if: ${{ needs.setup.outputs.examplesmatrix != ''}}
    strategy:
      fail-fast: false
      matrix:
        ${{ fromJson(needs.setup.outputs.examplesmatrix) }}

    steps:
      - uses: actions/checkout@v6

      - name: setup Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: install dependencies
        run: python -m pip install -r requirements.txt

      - name: build example
        timeout-minutes: 12
        env:
          PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
        run: |
          conda config --set notify_outdated_conda false
          nox -e ${{ matrix.example-name }} -- --no-website

      - name: check that the build did not create additional files in git
        run: |
          untracked="$(git ls-files --exclude-standard --others)"
          if [ -n "$untracked" ]; then
            printf >&2 "Error: running the example created untracked files:\n%s\n" "$untracked"
            exit 1
          fi

      - name: store example as a github artifact
        uses: actions/upload-artifact@v6
        with:
          name: example-${{ matrix.example-name }}
          path: docs/src/examples/*  # folders for each example will be merged later
          overwrite: true  # only keep the latest version of the example

  build-and-publish:
    # Run this job even if the generate-example job was skipped due to
    # no examples to run. I.e. only avoid if generate-example failed.
    if: ${{ always() && needs.generate-example.result != 'failure' }}
    # Permissions for the GITHUB_TOKEN (does not affect GH_DEPLOY_TOKEN)
    permissions: read-all
    needs: [setup, generate-example]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: setup Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: install dependencies
        run: python -m pip install -r requirements.txt

      - name: Download latest main branch built examples
        uses: actions/download-artifact@v7
        if: ${{ github.event_name == 'pull_request' }}
        with:
          path: docs/src/examples
          pattern: example-*
          github-token: ${{ secrets.GITHUB_TOKEN }}
          run-id: ${{ needs.setup.outputs.latest_docs_run }}
          merge-multiple: true

      - name: Overwrite examples with the ones built in this run
        uses: actions/download-artifact@v7
        with:
          path: docs/src/examples
          pattern: example-*
          merge-multiple: true

      - name: build documentation
        run: nox -e build_website

      - name: store documentation as github artifact to be downloaded by users
        uses: actions/upload-artifact@v6
        with:
          name: documentation
          path: docs/build/html/*
          overwrite: true  # only keep the latest version of the documentation

      - name: put documentation in the website
        run: |
          git clone https://github.com/$GITHUB_REPOSITORY --branch gh-pages gh-pages
          rm -rf gh-pages/.git
          cd gh-pages

          # deploys directly to the root of the website
          rm -rf *
          mv ../docs/build/html/* .

      - name: deploy to gh-pages
        if: github.event_name == 'push'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GH_DEPLOY_TOKEN }}
          publish_dir: ./gh-pages/
          force_orphan: true
          cname: atomistic-cookbook.org