Merge pull request WordPress#545 from WordPress/feature/466-ghactions…

…-ghpages-update-workflow

.gitattributes

@@ -1,9 +1,11 @@
 .github/ export-ignore
+build/ export-ignore
 docs/ export-ignore
 examples/ export-ignore
 tests/ export-ignore
 .codecov.yml export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore
 .phpcs.xml.dist export-ignore
+phpdoc.dist.xml export-ignore
 phpunit.xml.dist export-ignore

.github/workflows/lint.yml

@@ -49,4 +49,9 @@ jobs:
           composer-options: --ignore-platform-reqs
 
       - name: Lint against parse errors
+        if: ${{ matrix.php >= '7.2' }}
         run: composer lint -- --checkstyle | cs2pr
+
+      - name: Lint against parse errors
+        if: ${{ matrix.php < '7.2' }}
+        run: composer lint -- --exclude build --checkstyle | cs2pr

.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 }}

.gitignore

@@ -4,10 +4,17 @@ tests/coverage/*
 # Ignore composer related files
 /composer.lock
 /vendor
+build/ghpages/composer.lock
+build/ghpages/vendor
 
 # Ignore local overrides of the PHPCS config file.
 .phpcs.xml
 phpcs.xml
 
 # Ignore PHPUnit results cache file.
 .phpunit.result.cache
+
+# Ignore temporary files for ghpages builds.
+phpdoc.xml
+build/ghpages/.phpdoc
+build/ghpages/artifacts

build/ghpages/README.md

@@ -0,0 +1,27 @@
+Scripts to update the GitHub Pages website
+======================================
+
+The scripts in this directory are only for internal use to update the GitHub Pages website associated with this project whenever a new version of the Requests library is released.
+
+They are used in the [`update-website.yml`](https://github.com/WordPress/Requests/blob/develop/.github/workflows/update-website.yml) GitHub Actions workflow.
+
+To run a test build of the GitHub Pages site locally, execute the following steps:
+
+Preparation in this repo:
+* Pre-requisite: use PHP 7.2 or higher.
+* From within this subdirectory, run `composer update -W`.
+* Delete the `build/ghpages/artifacts` subdirectory completely.
+
+Preparation of the GitHub Pages branch:
+* Clone this repo a second time outside of the root of this clone and check out the `gh-pages` branch.
+* Create a new branch (git).
+* Delete the `api` directory completely.
+* Delete the `docs` directory completely.
+
+Switch to the project root directory in this clone and:
+* Run `php build/ghpages/update-docgen-config.php` to retrieve the latest tag number from the GH API and create/update the `phpdoc.xml` config.
+* If this was the first time you ran the above script, you now need to edit the `phpdoc.xml` file and update the path in the `<paths>` - `<output>` config to point to the `root/api` directory of the "gh-pages" clone of the repo.
+* Run `php build/ghpages/vendor/bin/phpdoc` to generate the API docs.
+* Run `php build/ghpages/update-markdown-docs.php --target=path/to/gh-pages/root` to generate versions of the markdown docs suitable for use in GH Pages.
+
+You can then use git diff to verify the GH Pages site was updated correctly.