Generate help command output for readme with github action

[swissbuechi]

After adding 2-3 features with new arguments I got to lazy to manually update the usage section in the README.md after every change.

So I've decided to write a simple github action which will handle the generation.

Usage

<!-- HELP-COMMAND-OUTPUT:START -->
...
<!-- HELP-COMMAND-OUTPUT:END -->

Implementation

Action
The github action generate-help-output.yml will run on every push.
If a change triggers a updates output of the homebrew autoupdate --help command, the action will create a commit and push the updated README.md file.

Script
The python 3 script generate-help-output.py will generate the output of the --help command and compare it to the current output in the usage section of the README.md file.

I will add the required start and stop tags after the initial PR creation, so we can see the changes made by the action.

[swissbuechi]

Test

Tag not found

Here you can see what happens when the tag is not found:
https://github.com/swissbuechi/homebrew-autoupdate/actions/runs/6829773030/job/18576552522

The same will happen if the content of the usage section is already up-to-date.

Tag found and content is outdated

Here is a run where it found the tag and updated the content of the usage section:
https://github.com/swissbuechi/homebrew-autoupdate/actions/runs/6829880297/job/18576856651

This commit was made by the action:
4cf6749
Seems like there was already a small offset from the documentation compared to the real execution of the command.

Tag found and content is already up-to-date

I will make a small change on the README.md file to demonstrate this case.
https://github.com/swissbuechi/homebrew-autoupdate/actions/runs/6829986114/job/18577163825
The commit and push will be skipped in this case.

Other error handling

Checkout the source code of generate-help-output.py, it should handle most common cases.

Know issues

A commit and push created by a github action will not trigger other actions.
If this should be an isse, it can be solved by creating a Github App to do the commit like in this example:

GitHub App

GitHub App. To do this, you'll need to go to >https://github.com/settings/apps/new or https://github.com/organizations/<org>/settings/apps/new and create an app with the following settings:

1. Uncheck Expire user authorization tokens
2. Uncheck Webhook Active
3. Set the following Repository permissions
   • Contents: Read & Write
   • Metadata: Read-only
   • Pull requests: Read & Write
   • Projects: Read-only

Once created, you'll need to generate a private key.

You'll then need to install the app to your account or org and add Action & Dependabot secrets for both the BOT_APP_ID and BOT_PRIVATE_KEY values which correspond to the App ID at the top of the page, and the private key you just created.

[MikeMcQuaid]

manually update the usage section in the README.md after every change.

Instead: remove this and link to https://docs.brew.sh/Manpage#autoupdate-subcommand-interval-options which is automatically updated.

[swissbuechi]

manually update the usage section in the README.md after every change.

Instead: remove this and link to https://docs.brew.sh/Manpage#autoupdate-subcommand-interval-options which is automatically updated.

I did not know this already existed.
Thanks a lot!

Still was a lot of fun creating my solution 😀

I will create a new PR.