feat: generate manual page automatically with cobra/doc

[ittner]

Add a command line switch "--man-page" to print an automatically generated manual page to stdout.

[mergify]

@ittner this pull request has failed checks 🛠

[ChristopherHX]

It would be nice to see the example output in the pr description.

I will rerun the CI later, to get the coverage result. Tests are passing, except for coverage which we see later.

The cmd package usually has coverage problems due to missing tests in the area, if the coverage is red only cplee (owner) can ignore the failure

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 76.64%. Comparing base (5a80a04) to head (0802e7e).
Report is 109 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #2352       +/-   ##
===========================================
+ Coverage   61.56%   76.64%   +15.07%     
===========================================
  Files          53       62        +9     
  Lines        9002     8177      -825     
===========================================
+ Hits         5542     6267      +725     
+ Misses       3020     1345     -1675     
- Partials      440      565      +125     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ChristopherHX]

Hmm, transcript from the man cli.

I could not figure out how to display the man page using your cli flag without seeing man page source code or storing it inside a file

act(1)                                                                                                                                                               act(1)

NAME
       act - Run GitHub actions locally by specifying the event name (e.g. push) or an action name directly.

SYNOPSIS
       **act [event name to run] [flags]

       If no event name passed, will default to "on: push" If actions handles only one event it will be used as default instead of "on: push"**

DESCRIPTION
       Run GitHub actions locally by specifying the event name (e.g. push) or an action name directly.

OPTIONS
       --action-cache-path="/home/codespace/.cache/act"      Defines the path where the actions get cached and host workspaces created.

       --action-offline-mode[=false]      If action contents exists, it will not be fetch and pull again. If turn on this,will turn off force pull

       -a, --actor="nektos/act"      user that triggered the event

       --artifact-server-addr="172.16.5.4"      Defines the address to which the artifact server binds.

       --artifact-server-path=""      Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not
       start.

       --artifact-server-port="34567"      Defines the port where the artifact server listens.

       -b, --bind[=false]      bind working directory to container, rather than copy

       --bug-report[=false]      Display system information for bug report

       --cache-server-addr="172.16.5.4"      Defines the address to which the cache server binds.

       --cache-server-path="/home/codespace/.cache/actcache"      Defines the path where the cache server stores caches.

       --cache-server-port=0      Defines the port where the artifact server listens. 0 means a randomly available port.

       --container-architecture=""      Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default  architecture.  Re‐
       quires Docker server API Version 1.41+. Ignored on earlier Docker server platforms.

       --container-cap-add=[]      kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE)

       --container-cap-drop=[]      kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE)

       --container-daemon-socket=""      URI to Docker Engine socket (e.g.: unix://~/.docker/run/docker.sock or - to disable bind mounting the socket)

       --container-options=""      Custom docker container options for the job container without an options property in the job definition

       --defaultbranch=""      the name of the main branch

       --detect-event[=false]      Use first event type from workflow as event that triggered the workflow

       -C, --directory="."       working directory

       -n, --dryrun[=false]      disable container creation, validates only workflow correctness

       --env=[]      env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv)

       --env-file=".env"      environment file to read and use as env in the containers

       -e, --eventpath=""      path to event JSON file

       --github-instance="github.com"      GitHub instance to use. Don't use this if you are not using GitHub Enterprise Server.

       -g, --graph[=false]      draw workflows

       -h, --help[=false]      help for act

       --input=[]      action input to make available to actions (e.g. --input myinput=foo)

       --input-file=".input"      input file to read and use as action input

       --insecure-secrets[=false]      NOT RECOMMENDED! Doesn't hide secrets while printing logs.

       -j, --job=""      run a specific job ID

       --json[=false]      Output logs in json format

       -l, --list[=false]      list workflows

       --local-repository=[]        Replaces   the   specified   repository   and   ref   with  a  local  folder  (e.g.  https://github.com/test/test@v0=/home/act/test  or
       test/test@v0=/home/act/test, the latter matches any hosts or protocols)

       --log-prefix-job-id[=false]      Output the job id within non-json logs instead of the entire name

       --man-page[=false]      Print a generated manual page to stdout

       --matrix=[]      specify which matrix configuration to include (e.g. --matrix java:13

       --network="host"      Sets a docker network name. Defaults to host.

       --no-cache-server[=false]      Disable cache server

       --no-recurse[=false]      Flag to disable running workflows from subdirectories of specified path in '--workflows'/'-W' flag

       --no-skip-checkout[=false]      Do not skip actions/checkout

       -P, --platform=[]      custom image to use per platform (e.g. -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04)

       --privileged[=false]      use privileged mode

       -p, --pull[=true]      pull docker image(s) even if already present

       -q, --quiet[=false]      disable logging of output from steps

       --rebuild[=true]      rebuild local action docker image(s) even if already present

       --remote-name="origin"      git remote name that will be used to retrieve url of git repo

       --replace-ghe-action-token-with-github-com=""      If you are using replace-ghe-action-with-github-com  and you want to use private actions on GitHub, you  have  to
       set personal access token

       --replace-ghe-action-with-github-com=[]       If you are using GitHub Enterprise Server and allow specified actions from GitHub (github.com), you can set actions on
       this. (e.g. --replace-ghe-action-with-github-com =github/super-linter)

       -r, --reuse[=false]      don't remove container(s) on successfully completed workflow(s) to maintain state between runs

       --rm[=false]      automatically remove container(s)/volume(s) after a workflow(s) failure

       -s, --secret=[]      secret to make available to actions with optional value (e.g. -s mysecret=foo or -s mysecret)

       --secret-file=".secrets"      file with list of secrets to read from (e.g. --secret-file .secrets)

       --use-gitignore[=true]      Controls whether paths specified in .gitignore should be copied into container

       --use-new-action-cache[=false]      Enable using the new Action Cache for storing Actions locally

       --userns=""      user namespace to use

       --var=[]      variable to make available to actions with optional value (e.g. --var myvar=foo or --var myvar)

       --var-file=".vars"      file with list of vars to read from (e.g. --var-file .vars)

       -v, --verbose[=false]      verbose output

       --version[=false]      version for act

       -w, --watch[=false]      watch the contents of the local repo and run when files change

       -W, --workflows="./.github/workflows/"      path to workflow file(s)

HISTORY
       6-Jun-2024 Auto generated by spf13/cobra

act 0.2.63                                                                        Jun 2024                                                                           act(1)

...I'm still undecided about this feature

[ittner]

...I'm still undecided about this feature

Hi @ChristopherHX !

A bit of rationale for this feature: I'm looking into packaging act for Debian and Ubuntu and manpages are required by both distro policies. I can imagine other distros having similar requirements.

Of course, manpages can be written manually (at the risk of leaving them outdated as the CLI changes) or I can keep a local patch use it to generate the pages when needed, but this code seems more useful if it is shared among potential users. Hugo and others uses a similar approach for generating man-pages, for example.

I though about having it optionally write the output to a file but I fear this can introduce more complexity that needed for potential users, as they will need to remember or look into another options instead of just redirecting with the shell... but perhaps my fear is undeserved and the output to a file is welcome.

[mergify]

@ittner this pull request is now in conflict 😩

[ittner]

Branch rebased to fix new conflict on go.sum/mod.

[ChristopherHX]

Thank your for outlining you intention here, we could technically hide the flag from help as this is more a packaging extension than a feature for people using act

I'm not blocking your plan to make it an official debian/ubuntu package, but be aware I already had the situation that tools like podman/buildah lacked bug fixes for thing fixed over 6 months ago

So a ppa is actually more important for people like me, I have scripts to host it with GitHub Pages

The auto merge of dependable bot updates is unfortunate for any PR that changes dependencies, especially if they would be open for an extended amount of time

[ChristopherHX]

https://github.com/russross/blackfriday

Note for reviewer: New dependency, last updated 4 years ago