name: Build Docs
on:
  push:
    branches:
      - autobuild-doc
jobs:
  doc:
    name: Build Docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8
      - name: Install CLI
        run: |
          python -m pip install -e .
      - name: Generate Autodoc
        run: |
          ./reference/_generate.py
          # bundle as tarball without the _generate.py script
          tar --exclude "*.py" -czf cli-reference.tar.gz reference/
      # upload as an artifact -- to download, use the GitHub APIs
      # you can find this workflow's ID by listing workflows using:
      #   https://docs.github.com/en/rest/reference/actions#list-repository-workflows
      # then find the last run for a branch:
      #   https://docs.github.com/en/rest/reference/actions#list-workflow-runs-for-a-repository
      #
      # and list artifacts for a run:
      #   https://docs.github.com/en/rest/reference/actions#list-workflow-run-artifacts
      - name: Upload Autodoc
        uses: actions/upload-artifact@v2
        with:
          name: cli-reference
          path: ./cli-reference.tar.gz

# build and release new docs as a release asset
name: Build Docs
on:
  release:
    types: [created]
jobs:
  doc:
    name: Build Docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
        with:
          python-version: 3.8
      - name: Install CLI
        run: |
          python -m pip install -e .
      - name: Generate Autodoc
        run: |
          ./reference/_generate.py
          # bundle as tarball without the _generate.py script
          tar --exclude "*.py" -czf cli-reference.tar.gz reference/
      # upload as a release asset
      - name: Upload Autodoc
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          # upload URL is pulled from the release event
          upload_url: ${{ github.event.release.upload_url }}
          asset_path: ./cli-reference.tar.gz
          asset_name: cli-reference.tar.gz
          asset_content_type: application/gzip

Update doc building to publish release asset
Update doc building to publish release asset

The automatic doc building in GH Actions will publish a release asset,
not a workflow artifact. This is necessary in order for the built docs
to be persistent (workflow artifacts expire).

The downside is that if docs.globus.org references a build artifact,
we might need to "backport" any doc fixes into an old release.
However, there should be no harm in doing so, and we aren't promising
externally that "released" docs are immutable.
