Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GH Actions: add GH Pages update workflow #545

Merged
merged 5 commits into from
Sep 17, 2021
Merged

GH Actions: add GH Pages update workflow #545

merged 5 commits into from
Sep 17, 2021

Commits on Sep 17, 2021

  1. 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
    @jrfnl
    jrfnl committed Sep 17, 2021
    Configuration menu
    Copy the full SHA
    3d78bdc View commit details
    Browse the repository at this point in the history

  2. 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 ?
    @jrfnl
    jrfnl committed Sep 17, 2021
    Configuration menu
    Copy the full SHA
    7aa4c89 View commit details
    Browse the repository at this point in the history

  3. 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.
    @jrfnl
    jrfnl committed Sep 17, 2021
    Configuration menu
    Copy the full SHA
    d11ed08 View commit details
    Browse the repository at this point in the history

  4. 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.
    @jrfnl
    jrfnl committed Sep 17, 2021
    Configuration menu
    Copy the full SHA
    1f3f033 View commit details
    Browse the repository at this point in the history

  5. 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
    @jrfnl
    jrfnl committed Sep 17, 2021
    Configuration menu
    Copy the full SHA
    09b1ea9 View commit details
    Browse the repository at this point in the history