python_docs.yml

name: Docs

# Maintenance: Create a reusable workflow to be more easily reused across release, push, and doc hot fixes
# this should include inputs on whether to release API docs, what version to release, and whether to rebuild /latest

on:
  push:
    branches:
      - develop
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - "examples/**"
  workflow_dispatch:

jobs:
  changelog:
    permissions:
      contents: write
    uses: ./.github/workflows/reusable_publish_changelog.yml

  docs:
    needs: changelog
    # Force Github action to run only a single job at a time (based on the group name)
    # This is to prevent "race-condition" in publishing a new version of doc to `gh-pages`
    concurrency:
      group: on-docs-build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Install poetry
        run: pipx install poetry
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.8"
          cache: "poetry"
      # Maintenance: temporarily until we drop Python 3.6 and make cfn-lint a dev dependency
      - name: Setup Cloud Formation Linter with Latest Version
        uses: scottbrenner/cfn-lint-action@ee9ee62016ef62c5fd366e6be920df4b310ed353 # v2.2.4
      - name: Install dependencies
        run: make dev
      - name: Lint documentation
        run: |
          make lint-docs
          cfn-lint examples/**/*.yaml
      - name: Setup doc deploy
        run: |
          git config --global user.name Docs deploy
          git config --global user.email docs@dummy.bot.com
          git config pull.rebase true
          git pull --rebase
      - name: Build docs website and API reference
        run: make release-docs VERSION="develop" ALIAS="stage"
      - name: Deploy all docs
        uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./api
          keep_files: true
          destination_dir: develop/api
      - name: Create redirect from old docs
        run: |
          git checkout gh-pages
          test -f 404.html && echo "Redirect already set" && exit 0
          git checkout develop -- 404.html
          git add 404.html
          git commit -m "chore: set docs redirect" --no-verify
          git push origin gh-pages -f