GH Actions: add an "update website" workflow

This new workflow will run when:
* A new release of Requests has been published.
* A pull request has been send in which updates the scripts which are involved in updating the website.

The workflow can also be manually triggered, but will not run in forks of this repo (as they can't update or publish the website).

:point_right: Open question: should the workflow always run for pushes to `stable` ?
Those will normally be the release pushes and the "next" version nr may not be known yet in that case, but if something is "off" with the website, an update to regen the website would now require a new tag (or manual trigger, but we'll have to see how well that works for this).

The script will:
* In the `prepare` job:
    - (Re-)Generate the API docs using phpDocumentor.
    - Prepare the `README` and the files in the `docs` directory for use in the website.
    - Upload the results as an artifact.
        The artifact will only be available for one day as it's only used in the next job.
* In the `createpr` job:
    - Download the artifact.
    - Remove outdated files and replace them with the newly generated ones.
        Note: files can be updated, as well as added/removed, so for the commits we need to make sure that both tracked as well as untracked changes are committed.
    - Create a PR to the `gh-pages` branch containing two commits:
        1. A commit for the API docs update.
            This commit _may_ be empty if no inline docs have been updated, though I suspect that will be exceedingly rare.
        2. A commit containing the remaining changes (docs + homepage).

For PRs created because the workflow or the associated scripts have changed, the PR title will be prefixed with `[TEST | DO NOT MERGE]` so the effect of workflow/script changes can still be verified, without updating the website with the docs for an unreleased `develop` version of Requests.
For those PRs, the website change PR will be based on the feature branch against `develop` as otherwise the action doesn't have access to the latest version of the workflow/scripts. For releases and manual triggering, the website change PR will always be based on the `stable` branch.

Note: these steps could be combined into one job, but for debugging, it felt cleaner to separate it into two jobs.

:point_right: Note: we'll need to monitor if a PR correctly gets created when there are no changes to the prose docs (committed via the `create-pr` action), but there are API doc changes (committed manually), I hope it will be, but we'll have to see.

Refs:
* https://github.com/marketplace/actions/create-pull-request
* https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md

.github/workflows/update-website.yml

@@ -0,0 +1,166 @@
+name: Build website
+
+on:
+  # Trigger the workflow whenever a new release is created.
+  release:
+    types:
+      - published
+  # And whenever this workflow or one of the associated scripts is updated.
+  pull_request:
+    paths:
+      - '.github/workflows/update-website.yml'
+      - 'build/ghpages/**'
+  # Also allow manually triggering the workflow.
+  workflow_dispatch:
+
+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
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            echo '::set-output name=BRANCH::${{ github.ref }}'
+          else
+            echo '::set-output name=BRANCH::stable'
+          fi
+
+      - name: Checkout code
+        uses: actions/checkout@v2
+        with:
+          ref: ${{ steps.base_branch.outputs.BRANCH }}
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '7.4'
+          ini-values: display_errors=On
+          coverage: none
+
+      # This will install the phpDocumentor PHAR, not the "normal" dependencies.
+      - name: Install Composer dependencies
+        uses: ramsey/composer-install@v1
+        with:
+          composer-options: "--working-dir=build/ghpages/"
+
+      - name: Update the phpDoc configuration
+        run: php build/ghpages/update-docgen-config.php
+
+      - name: Generate the phpDoc documentation
+        run: php build/ghpages/vendor/bin/phpdoc
+
+      - 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@v2
+        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:
+      - name: Checkout code
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+
+      - name: Download the prepared artifacts
+        uses: actions/download-artifact@v2
+        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/*
+
+      - name: Move the updated API doc files
+        run: mv -fv artifacts/api/* ./api/
+
+      # The commit should contain all changes in the API directory, both tracked and untracked!
+      - name: Commit the API docs separately
+        run: |
+          git config user.name 'GitHub Action'
+          git config user.email '${{ github.actor }}@users.noreply.github.com'
+          git add -A ./api/
+          git commit --allow-empty --message="GH Pages: update API docs for Requests ${{ github.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
+
+      # 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
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            echo '::set-output name=PR_TITLE_PREFIX::[TEST | DO NOT MERGE] '
+            echo '::set-output name=PR_BODY::Test run for the website update after changes to the automated scripts.'
+            echo '::set-output name=DRAFT::true'
+          else
+            echo '::set-output name=PR_TITLE_PREFIX::'
+            echo '::set-output name=PR_BODY::Website update after the release of Requests ${{ github.ref }}.'
+            echo '::set-output name=DRAFT::false'
+          fi
+
+      - name: Show status
+        run: git status -vv --untracked=all
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v3
+        with:
+          base: gh-pages
+          branch: feature/auto-ghpages-update-${{ github.ref }}
+          delete-branch: true
+          commit-message: "GH Pages: update other docs for Requests ${{ github.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).
+          labels: |
+            "Type: documentation"
+          reviewer: |
+            jrfnl
+            schlessera
+          draft: ${{ steps.get_pr_info.outputs.DRAFT }}