HexCasting/.github/workflows/build_docs.yml

name: Build the web book

on:
  push:
  workflow_dispatch:
    inputs:
      branch:
        description: 'Branch to generate docs from (default: same as workflow)'
        type: string
        required: false
      update-latest:
        description: Overwrite the latest books (and root, if releasing)
        type: boolean
        default: true
      release:
        description: Release
        type: boolean
        default: false
      publish:
        description: Package index to publish to
        type: choice
        options:
          - none
          - PyPI (release)
          - TestPyPI
      segment:
        description: 'Version segment to bump with Hatch (default: none)'
        type: string
        required: false

env:
  PYPI_PACKAGE: hexdoc

permissions:
  contents: read

concurrency:
  group: "docgen"
  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)      
    
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    permissions:
      contents: write
      pages: read

    outputs:
      pages-url: ${{ steps.get-url.outputs.pages-url }}
      matrix: ${{ steps.list-langs.outputs.matrix }}
      release: ${{ steps.check-release.outputs.release }}
      hexdoc: ${{ steps.get-hexdoc-cmd.outputs.hexdoc }}

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: pip
      
      - name: Get Pages url
        id: get-url
        run: |
          url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')
          echo "pages-url=$url" >> "$GITHUB_OUTPUT"
          echo "GITHUB_PAGES_URL=$url" >> "$GITHUB_ENV"          
      
      - name: Check if this is a release
        id: check-release
        run: |
          release=${{ github.event_name == 'workflow_dispatch' && inputs.release || startsWith(github.ref, 'refs/tags') || startsWith(github.event.head_commit.message, '[Release]') }}
          echo "release=$release" >> "$GITHUB_OUTPUT"          
      
      - name: Checkout input branch
        if: inputs.branch
        id: checkout-input
        uses: actions/checkout@v3
        with:
          ref: ${{ inputs.branch }}
          path: _branch_src

      - name: Get hexdoc command and set build variables
        id: get-hexdoc-cmd
        run: |
          if [[ '${{ steps.checkout-input.outcome }}' == 'skipped' ]]; then
            props='doc/properties.toml'
          else
            props='_branch_src/doc/properties.toml'
            echo "HATCH_GRADLE_DIR='_branch_src'" >> "$GITHUB_ENV"
          fi

          hexdoc="hexdoc $props --ci --is-release ${{ steps.check-release.outputs.release == true }} --update-latest ${{ github.event_name != 'workflow_dispatch' || inputs.update-latest }}"
          
          echo "$hexdoc"
          echo "hexdoc=$hexdoc" >> "$GITHUB_OUTPUT"
          echo "HEXDOC=$hexdoc" >> "$GITHUB_ENV"          

      - name: Install docgen from source
        run: pip install . hatch

      - name: List book languages
        id: list-langs
        run: |
          echo "matrix=$($HEXDOC --list-langs)" >> "$GITHUB_OUTPUT"
          if [[ $RUNNER_DEBUG ]]; then
            tree -I '__pycache__|Common|Fabric|Forge|venv'
          fi          

      - 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 docgen artifact
        uses: actions/upload-artifact@v3
        with:
          name: docgen-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: 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) }}

    env:
      GITHUB_PAGES_URL: ${{ needs.build.outputs.pages-url }}
      HEXDOC_GENERATE: ${{ needs.build.outputs.hexdoc }} --lang ${{ matrix.lang }} -o _site --clean

    steps:
      - uses: actions/checkout@v3
      - uses: ./.github/actions/install-artifact-wheel
        with:
          name: docgen-build
          python-version: "3.11"

      - name: Generate web book
        id: gen-normal
        continue-on-error: true
        run: $HEXDOC_GENERATE

      - name: Generate web book with missing translations
        if: steps.gen-normal.outcome == 'failure'
        run: $HEXDOC_GENERATE --allow-missing

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

      - name: Fail if the first generate step failed
        if: steps.gen-normal.outcome == 'failure'
        run: exit 1

  deploy-pages:
    runs-on: ubuntu-latest
    needs: [build, generate]

    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v3
      - uses: ./.github/actions/install-artifact-wheel
        with:
          name: docgen-build
          python-version: "3.11"
      
      - name: Checkout current Pages
        uses: actions/checkout@v3
        continue-on-error: true
        with:
          ref: gh-pages
          path: _site/dst

      - name: Download temporary Pages artifact
        uses: actions/download-artifact@v3
        with:
          name: github-pages-tmp
          path: _site/src/docs
      
      - name: Add new docs to site
        run: hexdoc_merge --src _site/src/docs --dst _site/dst/docs

      - name: Deploy to Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: _site/dst/docs
          target-folder: docs

  publish-pypi:
    runs-on: ubuntu-latest
    needs: build
    if: |-
      needs.build.outputs.release == 'true' &&
      (github.event_name != 'workflow_dispatch' || inputs.publish == 'PyPI (release)')      

    environment:
      name: pypi
      url: https://pypi.org/p/${{ env.PYPI_PACKAGE }}

    permissions:
      id-token: write

    steps:
      - name: Download docgen artifact
        uses: actions/download-artifact@v3
        with:
          name: docgen-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/${{ env.PYPI_PACKAGE }}

    permissions:
      id-token: write

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

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