Adjusting cobra help text #3465

Deflaimun · 2022-01-13T05:19:49Z

We created a python script that autogen docs for rpk based on the texts retrieved from rpk [command] -h generated by Cobra.
This script is living in a private tooling repo for now.

This PR adapts some texts in Cobra CLI to better reflect the expected output in the docs and to avoid unexpected results.

0x5d

Thanks so much for this! I left a couple small requests.

0x5d · 2022-01-13T15:53:30Z

src/python/gen-rpk-help-doc.py

+import re
+
+class Flag:
+  def __init__(self, value, type,explanation):


Let's run a linter on this to fix these small formatting inconsistencies. There's already a yapf config.

0x5d · 2022-01-13T16:33:31Z

src/python/gen-rpk-help-doc.py

+def get_explanation(process_line):
+    return process_line[:process_line.find("Usage")].rstrip("\n")
+
+def get_usage(process_line):


For each function which receives a line and parses it, could you please add comments about the structure of the line it expects, and the output?

andrewhsu · 2022-01-13T21:39:43Z

The python script src/python/gen-rpk-help-doc.py seems like it contains html specific for what we would like to display on the documentation site. Keeping that code in this repo strongly ties the documentation formatting to this site. Not sure if this repo is the best place for that type of script. What if we want to add CSS or javascript to that html output? That script may be better suited for a repo that has a pipeline built for docs generation. (my opinion, but willing to discuss with the docs team if there is a consideration i'm missing).

The changes in the golang files in this PR to fix capitalization and whitespacing LGTM.

andrewhsu · 2022-01-13T21:50:09Z

In addition, because rpk is using cobra, there are ways to generate man and markdown docs using the cobra golang package: https://github.com/spf13/cobra/blob/v1.3.0/doc/md_docs.md

An example of using cobra to generate docs for the GitHub CLI golang project can be found here: https://github.com/cli/cli/blob/trunk/cmd/gen-docs/main.go

Using cobra's doc generation may be easier than trying to line up --help whitespace output with expectations in a python script.

Deflaimun · 2022-01-13T22:57:13Z

In addition, because rpk is using cobra, there are ways to generate man and markdown docs using the cobra golang package: https://github.com/spf13/cobra/blob/v1.3.0/doc/md_docs.md

An example of using cobra to generate docs for the GitHub CLI golang project can be found here: https://github.com/cli/cli/blob/trunk/cmd/gen-docs/main.go

Using cobra's doc generation may be easier than trying to line up --help whitespace output with expectations in a python script.

Yeah, we considered it in our original ticket
https://github.com/vectorizedio/documentation/issues/25
but didn't went forward with it because the output is somewhat limiting.
Writing a script gives us the flexibility to write into any template that we like.

twmb · 2022-01-14T04:28:26Z

We could have a hidden help flag, --help-format that accepts the format. Cobra's docs are generated using Go templates (https://pkg.go.dev/text/template) so the output format is highly customizable. Parsing the current output may be stable, but I'm not sure if we want to change things or not, whereas a --help-format would allow you to programmatically control the output. What do you think?

Deflaimun · 2022-01-17T01:08:26Z

After discussion in our slack channel, this script won't be integrated into the pipeline. I'll be removing the .md file from this PR in result of that.

Deflaimun · 2022-01-17T01:10:10Z

Addressing the reported issues (formatting) as well.
Also, moving the .py file for the doc repo.
https://github.com/vectorizedio/www/pull/444

Docs PR:
#3529

For this PR we will only keep the change to the .go files

Deflaimun · 2022-01-18T15:42:08Z

@twmb since the output won't be directly integrated into the pipeline anymore, I guess there's not much reason to change the script now. Thank you for looking it up tho!

twmb · 2022-01-18T18:32:40Z

src/go/rpk/pkg/cli/cmd/generate/prometheus.go

-A comma-delimited list of the addresses (<host:port>) of all the redpanda nodes
-in a cluster. The port must be the one configured for the nodes' admin API
-(%d by default)`,
+		fmt.Sprintf(`A comma-delimited list of the addresses (<host>:<port>) of all the redpanda nodes in a cluster. The port must be the one configured for the nodes' admin API (%d by default)`,


I'm ok with this change (and may shorten the wording a bit later), but why merge in this PR?

Since the script that I wrote try to read each line, this extra was giving me some trouble. So it's a good idea to standardize it now.

twmb · 2022-01-18T18:33:34Z

src/go/rpk/pkg/cli/cmd/group/seek.go

-	cmd.Flags().StringVar(&toFile, "to-file", "", "seek to offsets as specified in the file")
-	cmd.Flags().StringArrayVar(&topics, "topics", nil, "only seek these topics, if any are specified")
-	cmd.Flags().BoolVar(&allowNewTopics, "allow-new-topics", false, "allow seeking to new topics not currently consumed (implied with --to-group or --to-file)")
+	cmd.Flags().StringVar(&to, "to", "", "Where to seek (start, end, unix second | millisecond | nanosecond)")


I'm ok with this, and I think we should standardize around capitlizing the first word in short help text lines. I previously thought that short help (the text after the flag itself) was lowercased usually, but looking at ls --help and rg --help, first-word-capitalization seems to be common.

src/go/rpk/pkg/cli/cmd/group/seek.go

Deflaimun · 2022-01-20T15:58:43Z

@twmb All points addressed.

Deflaimun requested review from 0x5d, LenaAn and twmb as code owners January 13, 2022 05:19

github-actions bot added area/docs area/rpk labels Jan 13, 2022

Deflaimun requested a review from coral-waters January 13, 2022 05:20

0x5d requested changes Jan 13, 2022

View reviewed changes

Deflaimun mentioned this pull request Jan 18, 2022

docs: Updating with all rpk commands #3529

Merged

Deflaimun force-pushed the rpk-help2 branch from c3cc717 to 25c2844 Compare January 18, 2022 15:30

github-actions bot removed the area/docs label Jan 18, 2022

twmb reviewed Jan 18, 2022

View reviewed changes

src/go/rpk/pkg/cli/cmd/group/seek.go Outdated Show resolved Hide resolved

docs: Adapting Cobra messages to the autogen script

c66eb32

Deflaimun force-pushed the rpk-help2 branch from 25c2844 to c66eb32 Compare January 18, 2022 20:20

Deflaimun changed the title ~~Create script to autogen docs for rpk~~ Adjusting cobra help text Jan 24, 2022

0x5d approved these changes Jan 24, 2022

View reviewed changes

0x5d merged commit 8712ad3 into redpanda-data:dev Jan 24, 2022

Deflaimun deleted the rpk-help2 branch January 24, 2022 18:33

This pull request was closed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adjusting cobra help text #3465

Adjusting cobra help text #3465

Deflaimun commented Jan 13, 2022 •

edited by 0x5d

Loading

0x5d left a comment

0x5d Jan 13, 2022

Deflaimun Jan 18, 2022

0x5d Jan 13, 2022

andrewhsu commented Jan 13, 2022

andrewhsu commented Jan 13, 2022

Deflaimun commented Jan 13, 2022

twmb commented Jan 14, 2022

Deflaimun commented Jan 17, 2022

Deflaimun commented Jan 17, 2022 •

edited

Loading

Deflaimun commented Jan 18, 2022

twmb Jan 18, 2022

Deflaimun Jan 18, 2022

twmb Jan 18, 2022

Deflaimun commented Jan 20, 2022

Adjusting cobra help text #3465

Adjusting cobra help text #3465

Conversation

Deflaimun commented Jan 13, 2022 • edited by 0x5d Loading

0x5d left a comment

Choose a reason for hiding this comment

0x5d Jan 13, 2022

Choose a reason for hiding this comment

Deflaimun Jan 18, 2022

Choose a reason for hiding this comment

0x5d Jan 13, 2022

Choose a reason for hiding this comment

andrewhsu commented Jan 13, 2022

andrewhsu commented Jan 13, 2022

Deflaimun commented Jan 13, 2022

twmb commented Jan 14, 2022

Deflaimun commented Jan 17, 2022

Deflaimun commented Jan 17, 2022 • edited Loading

Deflaimun commented Jan 18, 2022

twmb Jan 18, 2022

Choose a reason for hiding this comment

Deflaimun Jan 18, 2022

Choose a reason for hiding this comment

twmb Jan 18, 2022

Choose a reason for hiding this comment

Deflaimun commented Jan 20, 2022

Deflaimun commented Jan 13, 2022 •

edited by 0x5d

Loading

Deflaimun commented Jan 17, 2022 •

edited

Loading