GH Actions: add GH Pages update workflow

[jrfnl]

GH Pages: switch from APIGen to phpDocumentor

1. APIGen 4.x does not support "modern" PHP, and that includes such things as the PHP 5.5 ::class syntax.
2. There is an APIGen 5.x RC available, but that version is in its current state is no longer installable.
3. APIGen has not seen a release in over four years, nor a commit in more than three years and is currently unmaintained.

With that in mind, I've taken the decision to switch to the actively maintained phpDocumentor library to generate the API documentation.

This commit actions that decision by:

• Adding a base phpdoc.dist.xml configuration file.
• Adding a separate composer.json file for use when generating the API docs.
  The require-dev will pull in the phpDocumentor Phar via the shim package rather than install the individual dependencies.
• Adding this file and the build directory to the .gitattributes file for ignoring in distribution zips
• Adding the structure cache directory which will be used and the config overload file to the .gitignore file.

In a sister-PR to the gh-pages branch, the old apigen.neon config file will be removed.

Refs:

• https://github.com/ApiGen/ApiGen/releases
• https://tomasvotruba.com/blog/2017/09/04/how-apigen-survived-its-own-death/
• https://www.phpdoc.org/
• https://github.com/phpDocumentor/phpDocumentor/releases
• https://github.com/phpDocumentor/shim

GH Pages: add script to update/generate phpDoc config

This commit adds a script which can be run both locally as well as in a GH Actions workflow.

The script:

• Will retrieve the version number of the latest Requests release from the GH API.
• If no phpdoc.xml file exists, it will create a phpdoc.xml file based on the existing phpdoc.dist.xml file and make sure the title contains the correct version number.
• If a phpdoc.xml already exists, it will just and only update the title for the docs with the correct version number.

Includes a minor tweak to the PHP lint workflow to exclude the scripts in the build/ghpages directory from linting on PHP < 7.2.

Open question: once Requests 2.0.0 has been released, should we update the website to only contain the API docs for Requests 2.0.0 or should we keep a copy of the last Requests 1.x docs available as well ?

GH Pages: add script to update prose docs

This commit adds a script which can be run both locally as well as in a GH Actions workflow.

The script:

• Will take the README.md file from the main repo as well as the md files in the /docs/ directory and prepare them for use in the GH Pages website.
  This preparation includes:
  • Adding frontmatter to the files for use by Jekyll.
  • Replacing md in links with html.
  • Various other tweaks depending on the file.
• The script will, by default, place the adjusted files in the build/ghpages/artifacts directory. For local runs where there is already a separate clone of this repo available which has the gh-pages branch checked out, a --target=path/to/ghpages CLI argument can be passed to place the files directory in the gh-pages clone.

Includes a minor tweaks to the docs/README.md file for easier processing of that file.

This script effectively replaces the build.py script which is in the gh-pages branch. That script will be removed in a sister-PR to that branch.

GH Pages: add a README

... to the new directory containing the scripts documenting how these scripts can be run locally to test what changes would be made when the website would be updated.

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

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

👉 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

Fixes #466