HexCasting/.github/workflows/build_docs.yml

name: Build the web book

on:
  push:
  workflow_dispatch:
    inputs:
      publish:
        description: Package index to publish the docgen to
        type: choice
        options:
          - none
          - PyPI
          - TestPyPI
      segment:
        description: Version segment to bump with Hatch
        type: string
        required: false

env:
  HEXDOC: hexdoc doc/properties.toml --ci

permissions:
  contents: read

concurrency:
  group: "hexdoc"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest

    # only execute on the default branch or when invoked manually
    if: |-
      github.event_name == 'workflow_dispatch' ||
      github.ref == format('refs/heads/{0}', github.event.repository.default_branch)      
    
    outputs:
      matrix: ${{ steps.list-langs.outputs.matrix }}

    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install docgen
        run: pip install . hatch
      
      - name: List languages
        id: list-langs
        run: echo "matrix=$($HEXDOC --list-langs)" >> "$GITHUB_OUTPUT"
      
      - name: Export web book
        run: $HEXDOC --export-only

      - name: Bump version
        if: github.event_name == 'workflow_dispatch' && inputs.segment
        run: hatch version ${{ inputs.segment }}
        
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Build web book from ${{ github.ref }}
      
      - name: Build docgen
        run: hatch build
      
      - name: Upload hexdoc artifact
        uses: actions/upload-artifact@v3
        with:
          name: hexdoc-build
          path: dist/
      
      - name: Copy build to Pages
        run: |
          mkdir -p _site/dist
          cp dist/*.whl _site/dist/latest.whl
          cp dist/*.tar.gz _site/dist/latest.tar.gz          

      - name: Fix permissions
        run: |
          chmod -c -R +rX "out/" | while read line; do
            echo "::warning title=Invalid file permissions automatically fixed::$line"
          done          

      - name: Upload temporary Pages artifact
        uses: actions/upload-artifact@v3
        with:
          name: github-pages-tmp
          path: _site/
  
  generate:
    runs-on: ubuntu-latest
    needs: build
    continue-on-error: true

    strategy:
      fail-fast: false
      matrix:
        lang: ${{ fromJson(needs.build.outputs.matrix) }}

    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      
      - name: Download hexdoc artifact
        uses: actions/download-artifact@v3
        with:
          name: hexdoc-build

      - name: Install docgen
        run: pip install *.whl

      - name: Build web book
        run: $HEXDOC --lang ${{ matrix.lang }} -o _site

      - name: Upload temporary Pages artifact
        uses: actions/upload-artifact@v3
        with:
          name: github-pages-tmp
          path: _site/

  bundle-pages:
    runs-on: ubuntu-latest
    needs: generate

    steps:
      - name: Download temporary Pages artifact
        uses: actions/download-artifact@v3
        with:
          name: github-pages-tmp
          path: _site/

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v2

  deploy-pages:
    runs-on: ubuntu-latest
    needs: bundle-pages

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    permissions:
      id-token: write
      pages: write

    steps:
      - name: Deploy to Pages
        id: deployment
        uses: actions/deploy-pages@v2
        with:
          timeout: 300000 # 5 minutes

  publish-pypi:
    runs-on: ubuntu-latest
    needs: build
    if: |-
      github.event_name == 'workflow_dispatch' && inputs.publish == 'PyPI' ||
      startsWith(github.ref, 'refs/tags') ||
      startsWith(github.event.head_commit.message, '[Release]')      

    environment:
      name: pypi
      url: https://pypi.org/p/hexdoc

    permissions:
      id-token: write

    steps:
      - name: Download hexdoc artifact
        uses: actions/download-artifact@v3
        with:
          name: hexdoc-build
          path: dist

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

  publish-testpypi:
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'workflow_dispatch' && inputs.publish == 'TestPyPI'

    environment:
      name: testpypi
      url: https://test.pypi.org/p/hexdoc

    permissions:
      id-token: write

    steps:
      - name: Download hexdoc artifact
        uses: actions/download-artifact@v3
        with:
          name: hexdoc-build
          path: dist

      - name: Publish to TestPyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          repository-url: https://test.pypi.org/legacy/