GH Pages/GH Actions: create workflow to auto-update the website on a new release

[jrfnl]

It would be very nice if we could automate regenerating the site whenever a release tag is created on the master branch.

Based on the research I have done so far into how the site is set up, that would roughly involve the following steps/conditions:

• Run when a tag has been created on the master branch (release - published event I believe) and the CI for that branch has passed.
  Probably a good idea to also allow manual triggering of the workflow to allow rebuilding of the site intermittently.
• Install PHP at 7.1 or higher.
• Install ApiGen - I suspect at version 4.x for now.
• Update line 15 of the apigen.neon file in the gh-pages branch to reflect the name of the just released tag.
  The name of the tag should be available in GITHUB_REF or alternatively can be obtained via a call to the GH API or via a call to git.
  Refs:
  • https://docs.github.com/en/actions/reference/events-that-trigger-workflows#release
  • https://gist.github.com/lukechilds/a83e1d7127b78fef38c2914c4ececc3c
  • https://gist.github.com/rponte/fdc0724dd984088606b0
• Run ApiGen from the root of the gh-pages branch with the apigen.neon config.
  This will update the files in the gh-pages api directory.
• Install Python
• Run the buildtool.py script from the root of the gh-pages branch.
  This will update the index.md file and the files in the docs directory of the gh-pages branch.
• Install Ruby 2.7.x
• Run bundler install from the gh-pages root.
• Test whether the site will build without errors.
• Commit the resulting updated files.
  While working on and testing this workflow, commits should probably go to a feature branch so it can be reviewed that the workflow works as expected.
  Once the workflow has stabilized, it should be decided whether the changes should still be committed to a feature branch with the workflow opening a PR so the results will always be reviewed before the site is updated or to allow the workflow to commit to the gh-pages branch directly.

I get the impression that the scripting as it is currently assumes a setup with the repo checked out twice like this:

project root at `master` branch
  |- bin
  |- docs
  |- examples
  |- library
  |- tests
  |- project root at `gh-pages` branch
    |- __includes
    |- _layouts
    |- .. etc

Also note that for some of the above steps/actions, there may well be predefined actions available or even additional actions which would be useful to run.
See: https://github.com/marketplace?type=actions

One action which look interesting in this context:

• https://github.com/marketplace/actions/apigen-docs

For additional actions (future scope), I'm thinking along the lines of:

• Running a spellchecker over the generated site.
• Running a linter which checks for dead links over the generated site.

@rmccue Have you got any additional context which whomever will work on this should know ?

[jrfnl]

A few notes based on the experiences with the 1.8.0 release:

• We can probably remove the dependency on the Python script and replace that with a PHP or bash script to do the same.
• That script should make sure that:
  • the contents of the docs folder get copied over and frontmatter gets added to each page.
  • the pagename.md links in the docs folder are updated to .html, like in the "Previous/Next" links.
  • the Readme is copied over to index.md and various references like "rmccue/requests": ">=1.0" are replaced with GH API references as per commit b003240
  • Also see the existing script for details.
• Beware that the ApiGen docs contain two broken links when generated by default in api/class-Requests_Exception.html for the text <p>Like getCode(), but a string code.</p>. Those links need to be removed.
• There are also some links to internal classes/methods not being generated correctly by ApiGen which will need to be fixed. See commit e7e2344
• We may want to look into replacing ApiGen with phpDocumentor.

[jrfnl]

Status: ready & waiting (for other merges) to be pulled.