feat(docs): add UsageText to docs output for markdown and man page generation #1171

clok · 2020-08-06T16:51:21Z

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:

	before	after
markdown	https://gist.github.com/clok/ca1452874e372b02fe597f8ad65ca7f2	https://gist.github.com/clok/fe5e00c973575778f8e548263b5dba44
man	https://gist.github.com/clok/4ad90b19868709c86612ff76ee0e1350	https://gist.github.com/clok/a810114a454beee90d5134e9c8c533e8

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:

	before	after
markdown	https://gist.github.com/clok/ca1452874e372b02fe597f8ad65ca7f2	https://gist.github.com/clok/fe5e00c973575778f8e548263b5dba44
man	https://gist.github.com/clok/4ad90b19868709c86612ff76ee0e1350	https://gist.github.com/clok/a810114a454beee90d5134e9c8c533e8

Updated test suite
Generated local examples

Release Notes

(REQUIRED)

Add UsageText to docs output for markdown and man page generation

clok · 2020-11-02T05:54:59Z

@rliebz and @lynncyrin any chance that this can get merged?

rliebz

Thanks for the contribution, and sorry for the delay here. Got a few comments for you, but overall this looks great!

rliebz · 2020-11-06T01:48:50Z

docs.go

+	usageText := ""
+	if command.UsageText != "" {
+		// Remove leading and trailing newlines
+		preparedUsageText := strings.TrimSuffix(command.UsageText, "\n")


Is this meant to intentionally trim exactly up to one leading newline and one trailing newline? Or is the goal to trim all leading/trailing newlines?

For trimming all newlines from either side:

preparedUsageText := strings.Trim(command.UsageText, "\n")

For trimming all whitespace from either end:

preparedUsageText := strings.TrimSpace(command.UsageText)

preparedUsageText := strings.Trim(command.UsageText, "\n")

That is what I was looking for. Thank you for the suggestion! It was intended to remove all leading and trailing newlines.

rliebz · 2020-11-06T01:53:38Z

docs.go

+			// Format multi-line string as a code block
+			usageText = fmt.Sprintf("```\n%s\n```\n", preparedUsageText)
+		} else {
+			// Style a single line as a note


I'm curious—why use a block-quote for a one-line usage text? I'm not sure I understand why the style would be different for a one-liner versus a multi-liner.

It was a styling opinion more than anything. The use case I was considering was a very long one-line comment. Say 200+ characters in length. Within markdown there is no styling for the wrapping rules on a pre-formatted text block. This is particularly pronounced on Github where the CSS rules for a text block are quite narrow. Take the case below as an example.

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.

versus

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.

With a > note syntax, the markdown render will wrap the text accordingly. With the pre-formatted text block, it scrolls off screen making it difficult to read.

I dabbled with using > across many lines, but there were quite a few edge cases that made predicting the desired markdown format unruly.

docs.go

clok · 2020-11-14T17:24:55Z

Thank you very much for the feedback and suggestions. I will get to updating tests and responding to the feedback. I had hoped to get to it last week, but life and work kept pulling me away. Sorry for the delay!

clok · 2020-11-16T04:44:47Z

@rliebz Rebased with current master and updated with your feedback. Thank you again for the suggestions and comments. I noticed that the github actions are failing, but I can't tell if it is due to the changes I pushed. I am happy to address any issues that I can. Just let me know.

stale · 2021-02-14T18:58:54Z

This issue or PR has been automatically marked as stale because it has not had recent activity. Please add a comment bumping this if you're still interested in it's resolution! Thanks for your help, please let us know if you need anything else.

…neration

stale · 2021-02-26T17:04:04Z

This issue or PR has been bumped and is no longer marked as stale! Feel free to bump it again in the future, if it's still relevant.

clok · 2021-02-26T17:49:54Z

I put together an extension of sorts that accomplishes this feature (and more). https://github.com/clok/cdocs

I would really like to put these features in the mainline as I feel they are useful for all cli users. The plan was to get this initial work through the process and then extend from there.

I have updated the code, fixed the linting errors. Waiting for a review from maintainers. Thanks!

codefromthecrypt · 2021-05-20T09:37:37Z

any chance this can be reconsidered? It seems a pain to have to do external markdown generation to accomplish the same meanwhile, even if there's an add-on

rliebz

Sorry again for the delays here! This looks great, thanks for the contribution!

clok · 2021-05-21T12:00:05Z

Awesome! Happy to contribute.

codefromthecrypt · 2021-05-25T09:08:09Z

I think this may have drifted the -h output. As you'll notice, when multiple lines are present, it doesn't make a consistent indent.

USAGE:
   The '<version>' is from the "versions" command and installed if necessary.
The '<args>' are interpreted by Envoy.
The Envoy working directory is archived as $GETENVOY_HOME/runs/$epochtime.tar.gz upon termination.

Example:
$ getenvoy run 1.18.3 --config-path ./bootstrap.yaml

codefromthecrypt · 2021-05-25T09:09:32Z

the above was from this..

		Usage:     "Download and install a <version> of Envoy",
		ArgsUsage: "<version>",
		UsageText: fmt.Sprintf(`The '<version>' is from the "versions" command.
The Envoy <version> will be installed into $GETENVOY_HOME/versions/<version>

Example:
$ getenvoy install %s`, version.LastKnownEnvoy),

rliebz · 2021-06-01T01:10:55Z

@codefromthecrypt Would you mind opening an issue for that? If there's a bug in the behavior here, it's easier to keep track of if we have an issue with the expected behavior and steps to reproduce.

codefromthecrypt · 2021-06-01T02:39:42Z

@rliebz sure #1278

rliebz · 2021-06-01T02:40:18Z

Thanks!

clok · 2021-06-02T12:24:36Z

Nice catch on the regression. I'm sorry about that unintended change. I'll take a look at the issue and if it hasn't been addressed yet, I'll work on a fix for it.

clok · 2021-06-02T17:55:38Z

Got a PR up (#1279) to address the issue raised by @codefromthecrypt

clok requested a review from a team as a code owner August 6, 2020 16:51

clok requested review from rliebz and coilysiren and removed request for a team August 6, 2020 16:51

paulojblack previously approved these changes Aug 6, 2020

View reviewed changes

rliebz requested changes Nov 6, 2020

View reviewed changes

clok dismissed paulojblack’s stale review via 364d9c3 November 16, 2020 04:38

clok force-pushed the feat/docs-usage-text branch from 8f6a854 to 364d9c3 Compare November 16, 2020 04:38

clok requested a review from rliebz November 16, 2020 04:44

stale bot added the status/stale stale due to the age of it's last update label Feb 14, 2021

clok added 2 commits February 26, 2021 11:02

feat(docs): add UsageText to docs output for markdown and man page ge…

bb4f3fb

…neration

feat(docs): updated tests, DRYd up code, cleaned up string logic

8ea90fb

clok force-pushed the feat/docs-usage-text branch from 364d9c3 to 8ea90fb Compare February 26, 2021 17:04

stale bot removed the status/stale stale due to the age of it's last update label Feb 26, 2021

fix(lint): fixed go1.15 lint errors

1de80d6

coilysiren requested review from a team and removed request for coilysiren and rliebz April 23, 2021 19:44

rliebz approved these changes May 21, 2021

View reviewed changes

rliebz merged commit 581b769 into urfave:master May 21, 2021

codefromthecrypt mentioned this pull request Jun 1, 2021

v2 bug: multi-line UsageText doesn't consistently indent in help output #1278

Closed

4 tasks

clok deleted the feat/docs-usage-text branch June 2, 2021 17:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): add UsageText to docs output for markdown and man page generation #1171

feat(docs): add UsageText to docs output for markdown and man page generation #1171

clok commented Aug 6, 2020 •

edited

clok commented Nov 2, 2020

rliebz left a comment

rliebz Nov 6, 2020

clok Nov 15, 2020

rliebz Nov 6, 2020

clok Nov 15, 2020

clok commented Nov 14, 2020

clok commented Nov 16, 2020

stale bot commented Feb 14, 2021

stale bot commented Feb 26, 2021

clok commented Feb 26, 2021

codefromthecrypt commented May 20, 2021

rliebz left a comment

clok commented May 21, 2021 •

edited

codefromthecrypt commented May 25, 2021

codefromthecrypt commented May 25, 2021

rliebz commented Jun 1, 2021

codefromthecrypt commented Jun 1, 2021

rliebz commented Jun 1, 2021

clok commented Jun 2, 2021

clok commented Jun 2, 2021

feat(docs): add UsageText to docs output for markdown and man page generation #1171

feat(docs): add UsageText to docs output for markdown and man page generation #1171

Conversation

clok commented Aug 6, 2020 • edited

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Testing

Release Notes

clok commented Nov 2, 2020

rliebz left a comment

Choose a reason for hiding this comment

rliebz Nov 6, 2020

Choose a reason for hiding this comment

clok Nov 15, 2020

Choose a reason for hiding this comment

rliebz Nov 6, 2020

Choose a reason for hiding this comment

clok Nov 15, 2020

Choose a reason for hiding this comment

clok commented Nov 14, 2020

clok commented Nov 16, 2020

stale bot commented Feb 14, 2021

stale bot commented Feb 26, 2021

clok commented Feb 26, 2021

codefromthecrypt commented May 20, 2021

rliebz left a comment

Choose a reason for hiding this comment

clok commented May 21, 2021 • edited

codefromthecrypt commented May 25, 2021

codefromthecrypt commented May 25, 2021

rliebz commented Jun 1, 2021

codefromthecrypt commented Jun 1, 2021

rliebz commented Jun 1, 2021

clok commented Jun 2, 2021

clok commented Jun 2, 2021

clok commented Aug 6, 2020 •

edited

clok commented May 21, 2021 •

edited