What type of PR is this?

(REQUIRED)

• bug
• cleanup
• documentation
• feature

What this PR does / why we need it:

(REQUIRED)

As a tools developer, I find the UsageText field to be useful in providing details on what a command does and how to use it. A good example is with gwsm

For example, the command gwsm diff has as detailed description that helps the user know how to use the command.

$ gwsm diff --help
NAME:
   gwsm diff - View diff of local vs. namespace

USAGE:

View the diff of the local environment against a given command running on a pod within a namespace.

This will retrieve the stored secrets within AWS Secrets Manager and map them via
the secrets.yml file used by the 'summon' CLI tool to generate the current state of
Environment Variables for a given stage.

The AWS Secrets Manager names are assumed to be stored as '<SECRETS_GROUP>_NAME'
in the ConfigMap. Example: 'RDS_SECRET_NAME: rds/staging/service-yolo'

From the root of the service, the required files are typically found below:

The path to the configmap.yaml file is within the kubernetes deployment.
This is typically .kube/<stage>/05-configmap.yaml

The path to the secrets.yml is typically .docker/secrets.yaml

It will then grab current environment for a specific process running within a Pod in a given Namespace.

This is achieved by inspecting the /proc/<PID>/environ for the given process. This method uses
'/bin/bash -c' as the base command to perform the PID inspection via 'ps faux'.

The 'filter-prefix' flag will exclude any values that start with the flagged prefixes from display.

The 'exclude' flag will exclude any values where the KEY matches exactly from display.


OPTIONS:
   --secrets value, -s value        Path to secrets.yml (default: ".docker/secrets.yml")
   --configmap value, -c value      Path to configmap.yaml
   --namespace value, -n value      Kube Namespace list Pods from
   --cmd value                      Command to inspect (default: "node")
   --filter-prefix value, -f value  List of prefixes (csv) used to filter values from display. Set to "" to remove any filters. (default: "npm_,KUBERNETES_,API_PORT")
   --exclude value                  List (csv) of specific env vars to exclude values from display. Set to "" to remove any exclusions. (default: "PATH,SHLVL,HOSTNAME")
   --secret-suffix value            Suffix used to find ENV variables that denote the Secret Manager Secrets to lookup (default: "_NAME")
   --help, -h                       show help (default: false)

I would like for the docs generation (ToMarkdown and ToMan) to include this help text in the docs.

See the before and after here:

Which issue(s) this PR fixes:

(REQUIRED)

N/A - New feature

Testing

Updated a local copy of an existing tool (gwsm) with the delta applied and generated before/after docs.

See the before and after here:

• Updated test suite
• Generated local examples

Release Notes

(REQUIRED)

Add UsageText to docs output for markdown and man page generation