build_deploy_pdoc.yml

name: API docs / pdoc3 

# We should trigger this from an upload event 

on:
  push:
    branches: [master, dev]

  workflow_run:
    workflows: ["Conda Deployment"]
    branches: [master]
    types: 
      - completed

  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
  
      - name: Cache conda
        uses: actions/cache@v1
        env:
        # Increase this value to reset cache if etc/example-environment.yml has not changed
          CACHE_NUMBER: 0
        with:
          path: |
            ~/conda_pkgs_dir
            ~/.cache/pip
            
          key: ubu-pdoc-conda-${{ env.CACHE_NUMBER }}-${{ hashFiles('.github/workflows/resources/conda_api_docs_environment.yml') }}

      - name: Miniconda + Cache
        uses: conda-incubator/setup-miniconda@v2
        with:
            miniconda-version: "latest"
            environment-file: .github/workflows/resources/conda_api_docs_environment.yml
            activate-environment: conda-build-docs
            python-version: 3.7
            use-only-tar-bz2: true # IMPORTANT: This needs to be set for caching to work properly!


      - name: Install quagmire 
        shell: bash -l {0}
        run: |
          VERSION=`python setup.py --version`
          # install latest quagmire via conda, then over-ride with this source code
          pip install -e .

      - name: Build docs with pdoc
        shell: bash -l {0}
        run: |
          VERSION=`python setup.py --version`
          echo "VERSION=$(echo $VERSION)" >> $GITHUB_ENV
          mkdir -p docs
          cd docs
          pdoc --config latex_math=True --html -o api --force quagmire

      # Here we can add an action to build the jupyter book to a different directory 
      # and then they can be uploaded together. The jupyter book can contain a link to the
      # API docs.

      # Note deploy key needs the ----BEGIN ... KEY---- lines too
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        
        with:
          deploy_key: ${{ secrets.GH_PAGES_DEPLOY_PR_KEY }}
          destination_dir: ${{ env.VERSION }}_api
          publish_dir: docs/api/quagmire