update-website.yml

name: Build website

on:
  # Trigger the workflow whenever a new tag is created.
  push:
    tags:
      - '**'
  # And whenever this workflow or one of the associated scripts is updated.
  pull_request:
    branches-ignore:
      - 'stable'
    paths:
      - '.github/workflows/update-website.yml'
      - 'build/ghpages/**'
  # Also allow manually triggering the workflow.
  workflow_dispatch:

# Cancels all previous workflow runs for the same branch that have not yet completed.
concurrency:
  # The concurrency group contains the workflow name and the branch name.
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  pull-requests: write
  contents: write

jobs:
  prepare:
    name: "Prepare website update"
    # Don't run on forks.
    if: github.repository == 'WordPress/Requests'

    runs-on: ubuntu-latest
    steps:
      # By default use the `stable` branch as the published docs should always
      # reflect the latest release.
      # For testing changes to the workflow or the scripts, use the PR branch
      # to have access to the latest version of the workflow/scripts.
      - name: Determine branch to use
        id: base_branch
        env:
          REF: ${{ github.ref }}
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "BRANCH=$REF" >> $GITHUB_OUTPUT
          else
            echo 'BRANCH=stable' >> $GITHUB_OUTPUT
          fi

      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ steps.base_branch.outputs.BRANCH }}

      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          ini-values: display_errors=On
          coverage: none
          tools: phpdoc
        env:
          fail-fast: true

      - name: Update the phpDoc configuration
        run: php build/ghpages/update-docgen-config.php

      - name: Generate the phpDoc documentation
        run: phpDocumentor

      - name: Transform the markdown docs for use in GH Pages
        run: php build/ghpages/update-markdown-docs.php

      # Retention is normally 90 days, but this artifact is only for review
      # and use in the next step, so no need to keep it for more than a day.
      - name: Upload the artifacts folder
        uses: actions/upload-artifact@v4
        if: ${{ success() }}
        with:
          name: website-updates
          path: ./build/ghpages/artifacts
          if-no-files-found: error
          retention-days: 1

  createpr:
    name: "Create website update PR"
    needs: prepare
    # Don't run on forks.
    if: github.repository == 'WordPress/Requests'

    runs-on: ubuntu-latest
    steps:
      # PRs based on the "pull request" event trigger will contain changes from the
      # current `develop` branch, so should not be published as the website should
      # always be based on the latest release.
      - name: Determine PR title prefix, body and more
        id: get_pr_info
        env:
          REF_NAME: ${{ github.ref_name }}
          TAG_NAME: ${{ github.event.release.tag_name }}
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "REF=$REF_NAME" >> $GITHUB_OUTPUT
            echo 'PR_TITLE_PREFIX=[TEST | DO NOT MERGE] ' >> $GITHUB_OUTPUT
            echo 'PR_BODY=Test run for the website update after changes to the automated scripts.' >> $GITHUB_OUTPUT
            echo 'DRAFT=always-true' >> $GITHUB_OUTPUT
          else
            echo "REF=$TAG_NAME" >> $GITHUB_OUTPUT
            echo 'PR_TITLE_PREFIX=' >> $GITHUB_OUTPUT
            echo "PR_BODY=Website update after the release of Requests $TAG_NAME." >> $GITHUB_OUTPUT
            echo 'DRAFT=false' >> $GITHUB_OUTPUT
          fi

      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: gh-pages

      - name: Download the prepared artifacts
        uses: actions/download-artifact@v4
        with:
          name: website-updates
          path: artifacts

      # Different version of phpDocumentor may add/remove files for CSS/JS etc.
      # Similarly, a new Requests major may remove classes.
      # So we always need to make sure that the old version of the API docs are
      # cleared out completely.
      - name: Clear out the API directory
        run: rm -vrf ./api-2.x/*

      - name: Move the updated API doc files
        run: mv -fv artifacts/api-2.x/* ./api-2.x/

      # The commit should contain all changes in the API directory, both tracked and untracked!
      - name: Commit the API docs separately
        env:
          ACTOR: ${{ github.actor }}
        run: |
          git config user.name 'GitHub Action'
          git config user.email "$ACTOR@users.noreply.github.com"
          git add -A ./api-2.x/
          git commit --allow-empty --message="GH Pages: update API docs for Requests ${{ steps.get_pr_info.outputs.REF }}"

      # Similar to the API docs, files could be removed from the prose docs, so
      # make sure that the directory is cleared out completely beforehand.
      - name: Clear out the docs directory
        run: rm -vf ./docs/*

      - name: Move the other updated files
        run: |
          mv -fv artifacts/docs/* ./docs
          mv -fv artifacts/_includes/* ./_includes
          mv -fv artifacts/index.md ./index.md

      - name: Verify artifacts directory is now empty
        run: ls -alR artifacts

      # The directory is also gitignored, but just to be sure.
      - name: Remove the artifacts directory
        run: rmdir --ignore-fail-on-non-empty --verbose ./artifacts

      - name: Show status
        run: git status -vv --untracked=all

      - name: Create pull request
        uses: peter-evans/create-pull-request@v7
        with:
          base: gh-pages
          branch: feature/auto-ghpages-update-${{ steps.get_pr_info.outputs.REF }}
          delete-branch: true
          sign-commits: true
          commit-message: "GH Pages: update other docs for Requests ${{ steps.get_pr_info.outputs.REF }}"
          title: "${{ steps.get_pr_info.outputs.PR_TITLE_PREFIX }}:books: Update GHPages website"
          body: |
            ${{ steps.get_pr_info.outputs.PR_BODY }}

            This PR is auto-generated by [create-pull-request](https://github.com/peter-evans/create-pull-request) using the `.github/workflows/update-website.yml` workflow.
          labels: |
            Type: documentation
          reviewers: |
            jrfnl
            schlessera
          draft: ${{ steps.get_pr_info.outputs.DRAFT }}

      # Test that the site builds correctly.
      - name: Checkout the newly created branch
        uses: actions/checkout@v4
        with:
          ref: feature/auto-ghpages-update-${{ steps.get_pr_info.outputs.REF }}

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          # Use the version as per https://pages.github.com/versions/.
          ruby-version: 3.3.4
          bundler-cache: true

      - name: Test building the GH Pages site
        run: bundle exec jekyll build