HexCasting/.github/workflows/hexdoc.yml

name: "[Reusable] Build and publish a hexdoc project"

on:
  workflow_call:
    inputs:
      python-version:
        description: Python version to install
        type: string
        required: true
      checkout:
        description: Whether to check out the branch specified in `branch`
        type: boolean
        required: true
      branch:
        description: Branch to generate docs from
        type: string
        required: false
      publish-latest-and-root:
        description: Overwrite `/v/latest` (and `/`, if releasing)
        type: boolean
        required: true
      publish-release:
        description: Overwrite `/v/<current_version>`
        type: boolean
        required: true
      bump-version-segment:
        description: Version segment to bump with Hatch
        type: string
        required: false
    outputs:
      publish-release:
        description: Value of publish-release input for convenience.
        value: ${{ jobs.build.outputs.release }}

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    
    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.parse-inputs.outputs.release }}
      branch:        ${{ steps.parse-inputs.outputs.branch }}
      hexdoc-common: ${{ steps.parse-inputs.outputs.hexdoc-common }}
      hexdoc:        ${{ steps.parse-inputs.outputs.hexdoc }}

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: ${{ inputs.python-version }}
          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: Parse inputs
        id: parse-inputs
        run: |
          release=${{  inputs.publish-release }}
          update_latest=${{ inputs.publish-latest-and-root }}
          
          if [[ ${{ inputs.checkout }} == true ]]; then
            branch='${{ inputs.branch }}'
            props=_checkout/doc/properties.toml
            echo "HATCH_GRADLE_DIR=_checkout" >> "$GITHUB_ENV"
          else
            branch=none
            props=doc/properties.toml
          fi
          
          hexdoc_common="--is-release $release --update-latest $update_latest"
          hexdoc="hexdoc $props --ci $hexdoc_common"

          echo "HEXDOC=$hexdoc" >> "$GITHUB_ENV"
          
          echo "release=$release"             >> "$GITHUB_OUTPUT"
          echo "update-latest=$update_latest" >> "$GITHUB_OUTPUT"
          echo "branch=$branch"               >> "$GITHUB_OUTPUT"
          echo "hexdoc-common=$hexdoc_common" >> "$GITHUB_OUTPUT"
          echo "hexdoc=$hexdoc"               >> "$GITHUB_OUTPUT"          
      
      - name: Checkout input branch
        if: steps.parse-inputs.outputs.branch != 'none'
        id: checkout-input
        uses: actions/checkout@v3
        with:
          ref: ${{ steps.parse-inputs.outputs.branch }}
          path: _checkout

      - 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: inputs.bump-version-segment
        run: hatch version "${{ inputs.bump-version-segment }}"
        
      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Build web book from ${{ github.ref }}
      
      - name: Build package
        run: hatch build
      
      - name: Upload package artifact
        uses: actions/upload-artifact@v3
        with:
          name: hexdoc-build
          path: dist

      - name: Copy build to Pages
        if: steps.parse-inputs.outputs.update-latest
        run: |
          mkdir -p _site/v/latest/dist
          cp -r dist _site/v/latest/dist          

      - name: Upload temporary Pages artifact
        if: steps.parse-inputs.outputs.update-latest
        uses: actions/upload-artifact@v3
        with:
          name: github-pages-tmp
          path: _site

      - name: Add job summary
        run: echo "Built version \`$(hatch version)\` from commit \`$(git rev-parse --short "$GITHUB_SHA")\`." >> $GITHUB_STEP_SUMMARY
  
  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: ${{ needs.build.outputs.hexdoc }} --lang ${{ matrix.lang }} -o _site --clean

    steps:
      - uses: actions/checkout@v3
      - uses: ./.github/actions/install-artifact-wheel
        with:
          name: hexdoc-build
          python-version: ${{ inputs.python-version }}

      - name: Checkout input branch
        if: needs.build.outputs.branch != 'none'
        uses: actions/checkout@v3
        with:
          ref: ${{ needs.build.outputs.branch }}
          path: _checkout

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

      - name: Generate web book with missing translations
        if: steps.gen-normal.outcome == 'failure'
        run: $HEXDOC --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: |
          echo "::error::Missing some i18n keys."
          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: hexdoc-build
          python-version: ${{ inputs.python-version }}
      
      - 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 ${{ needs.build.outputs.hexdoc-common }} --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