docs.yml

name: Build docs

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
      - public
      - dev

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Cache dependencies
        id: pip-cache
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip

      - name: Checkout code
        uses: actions/checkout@v3

      - name: Checkout cebra figures
        uses: actions/checkout@v3
        with:
          repository: AdaptiveMotorControlLab/cebra-figures
          path: docs/source/cebra-figures
          ref: main

      - name: Checkout assets
        uses: actions/checkout@v3
        with:
          repository: AdaptiveMotorControlLab/cebra-assets
          path: assets
          ref: main

      - name: Add assets to repo
        run: |
          cp -r assets/* .
          rm -r assets

      - name: Checkout cebra demos
        uses: actions/checkout@v3
        with:
          repository: AdaptiveMotorControlLab/cebra-demos
          path: docs/source/demo_notebooks
          ref: main

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install package
        run: |
          python -m pip install --upgrade pip setuptools wheel
          # NOTE(stes) Pandoc version must be at least (2.14.2) but less than (4.0.0).
          # as of 29/10/23. Ubuntu 22.04 which is used for ubuntu-latest only has an 
          # old pandoc version (2.9.). We will hence install the latest version manually.
          # previou: sudo apt-get install -y pandoc
          wget https://github.com/jgm/pandoc/releases/download/3.1.9/pandoc-3.1.9-1-amd64.deb 
          sudo dpkg -i pandoc-3.1.9-1-amd64.deb 
          rm pandoc-3.1.9-1-amd64.deb 
          pip install torch --extra-index-url https://download.pytorch.org/whl/cpu
          pip install '.[docs]'

      - name: Build docs
        run: |
          ls docs/source/cebra-figures
          # later also add the -n option to check for broken links
          export SPHINXOPTS="-W --keep-going -n"
          make docs

      # NOTE(stes): To avoid issues as observed in
      # https://github.com/AdaptiveMotorControlLab/CEBRA/pull/20, we modified
      # this workflow to not rely on PATs. All repos except for the website
      # repo are public and only read access is required, so we simply removed
      # the tokens from the checkout actions.
      #
      # For pushing the docs, I temporarily disabled the staging repo, which
      # does not add anything informative to the contributor anyways, as it just
      # tests whether or not docs can be pushed (the staging branch is not deployed).
      #
      # The production branch will be built after the PR is merged to main.
      #
      # Commented code for staging branch:

      #- name: Deploy docs (staging)
      #  uses: cpina/github-action-push-to-another-repository@main
      #  if: github.ref != 'refs/heads/main'
      #  env:
      #    API_TOKEN_GITHUB: ${{ secrets.GH_PAT_WEBSITE }}
      #  with:
      #    source-directory: 'docs/page'
      #    destination-github-username: 'stes'
      #    destination-repository-name: 'cebra-ai'
      #    user-name: stes
      #    user-email: steffen@bethgelab.org
      #    target-branch: staging

      - name: Deploy docs (production)
        uses: cpina/github-action-push-to-another-repository@main
        if: github.ref == 'refs/heads/main'
        env:
          API_TOKEN_GITHUB: ${{ secrets.GH_PAT_WEBSITE }}
        with:
          source-directory: 'docs/page'
          destination-github-username: 'stes'
          destination-repository-name: 'cebra-ai'
          user-name: stes
          user-email: steffen@bethgelab.org
          target-branch: main