docs.yml

name: Docs

# Controls when the action will run.
on:
  workflow_call:

jobs:
  docs:
    # defining this job separately allows to refer to it later as job.needs dependency
    runs-on: ubuntu-latest
    steps:

      - name: Checking out the repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: main

      - name: Setting up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: pip
          cache-dependency-path: |
            ci/requirements.txt

      - name: Install required system packages
        shell: sh
        run: |
          PLATFORM="$(echo "$RUNNER_OS" | tr '[:upper:]' '[:lower:]')"
          REQFN="ci/requirements_$PLATFORM.txt"
          if [ "$PLATFORM" = "linux" ] && [ -f "$REQFN" ]; then
            sudo apt-get -y install $(sed -e '/^\s*#/d' "$REQFN")
          elif [ "$PLATFORM" = "windows" ] && [ -f "$REQFN" ]; then
            choco install $(sed -e '/^\s*#/d' "$REQFN")
          else
            echo "macro sys_install_req(): platform '$PLATFORM' not implemented yet."
          fi

      - name: Install dependencies
        shell: sh
        run: |
          [ -d "/c/miniconda" ] && /c/miniconda/condabin/activate.bat
          python -m pip install --upgrade pip
          python -m pip install --progress-bar=off -r ci/requirements.txt

      - name: Check
        shell: sh
        run: tox -e check -v

      - name: Generate documentation
        shell: sh
        run: tox -e docs -v

      - name: Upload docs for finalization later
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: dist/docs

      # - name: Upload generated documentation
      #   uses: peaceiris/actions-gh-pages@v3
      #   with:
      #     github_token: ${{ secrets.GITHUB_TOKEN }}
      #     publish_dir: ./dist/docs