doc-extraction.yml

name: Extract And Publish Documentation

defaults:
  run:
    shell: 'bash -eo pipefail {0}'

on:
  push:
    branches: [ main, fix-doc-generation ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    if: github.repository == 'hylo-lang/hylo'
    runs-on: macos-15
    env:
      llvm_url_prefix: https://github.com/hylo-lang/llvm-build/releases/download/20240303-215025
      llvm_package_basename: llvm-17.0.6-arm64-apple-darwin23.3.0-MinSizeRel
      swift-version: '5.10'

    steps:
    - uses: actions/checkout@v4
      with:
        submodules: true
        show-progress: false

    - name: Install Jazzy
      run: |
        sudo gem install jazzy

    - name: Setup swift
      uses: SwiftyLab/setup-swift@latest
      with:
        swift-version: ${{ env.swift-version }}
        cache-snapshot: false # Workaround for https://github.com/SwiftyLab/setup-swift/issues/315

    - name: Install LLVM and create its pkgconfig file
      # 7z doesn't support decompressing from a stream or we'd do this all as one statement. Maybe
      # we should find a way to use zstd on windows.
      run: >-
        curl --no-progress-meter -L -O
        -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}"
        ${{ env.llvm_url_prefix }}/${{ env.llvm_package_basename }}.tar.zst

        tar -x --zstd -f ${{ env.llvm_package_basename }}.tar.zst

        PATH="${{ github.workspace }}/${{ env.llvm_package_basename }}/bin:$PATH"
        ./Tools/make-pkgconfig.sh llvm.pc

    - name: Prepare shell environment
      run: |
        echo "PKG_CONFIG_PATH=${{ github.workspace }}
        REPO_SANS_OWNER=${GITHUB_REPOSITORY##*/}
        REF_URL_COMPONENT=${GITHUB_REF##*/}
        HYLO_ENABLE_DOC_GENERATION=1
        " >> "${GITHUB_ENV}"

    - uses: actions/cache@v4
      with:
        path: .build
        key: ${{ runner.os }}-debug-spm-${{ hashFiles('./**/Package.resolved') }}
        restore-keys: |
          ${{ runner.os }}-debug-spm-

    - name: Compute the Extraction Targets
      # The format of the ${GITHUB_ENV} file is extremely restrictive; it apparently only supports
      # lines of the form:
      #
      #   <variable-name>=<one-line-of-text>
      #
      # And a multiline version
      # (https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings).
      # It is not interpreted directly by a shell, so any quotes or other special characters are
      # taken literally.

      # FIXME: REF_URL_COMPONENT computation is probably wrong for some refs.
      run: |
        echo "EXTRACTION_TARGETS=$(
          swift package dump-package |
          jq '.targets | map(select(.type | test("^(regular|executable)$"))) | .[].name' |
          xargs
        )
        " >> "${GITHUB_ENV}"
        
    - name: Generate Index Page
      run: |
        mkdir -p _site
        Tools/gyb.py \
        --line-directive '<!-- file: %(file)s line: %(line)s -->' \
        -DROOT_URL="https://hylo-lang.org/${REPO_SANS_OWNER}" \
        -DEXTRACTION_TARGETS="${EXTRACTION_TARGETS}" \
        -DGITHUB_REPOSITORY="${GITHUB_REPOSITORY}" \
        Tools/doc-index.html.gyb -o _site/index.html
        
    - name: Extract with DocC
      run: |
        export PKG_CONFIG_PATH
        for TARGET in ${EXTRACTION_TARGETS}; do
          mkdir -p _site/docc/"$TARGET"
          Tools/retry-once swift package --allow-writing-to-directory ./_site \
          generate-documentation \
          --target "$TARGET" \
          --output-path _site/docc/"${TARGET}" \
          --experimental-documentation-coverage --level brief \
          --enable-inherited-docs \
          --transform-for-static-hosting \
          --hosting-base-path "${REPO_SANS_OWNER}/docc/${TARGET}" \
          --source-service github \
          --source-service-base-url "https://github.com/${GITHUB_REPOSITORY}/blob/${REF_URL_COMPONENT}" \
          --checkout-path "$(pwd)"
        done

    - name: Extract with Jazzy
      run: |
        export PKG_CONFIG_PATH
        for TARGET in ${EXTRACTION_TARGETS}; do
          mkdir -p _site/jazzy/"$TARGET"
          jazzy \
          --source-host-files-url "https://github.com/${GITHUB_REPOSITORY}/blob/${REF_URL_COMPONENT}" \
          --module $(echo "$TARGET" | sed -e 's/-/_/g') \
          --module-version "${{ github.event.release.tag_name }}" \
          --copyright "© $(date '+%Y') The Hylo Authors. (Last updated: $(date '+%Y-%m-%d'))" \
          --config .jazzy.yml \
          --output _site/jazzy/"$TARGET" \
          --min-acl private
        done

    - name: Setup Pages
      uses: actions/configure-pages@v5

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

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3

  # Deployment job
  deploy:
    if: github.repository == 'hylo-lang/hylo'
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4