Conversation
vilmibm
left a comment
There was a problem hiding this comment.
This is really cool! Thank you!
Please update this so it is accessed via gh help reference instead of having it print as part of gh help or as usage information. It's too much information to print in those cases but is a great help topic.
|
@vilmibm totally missed that it is printed in |
|
We just merged some stuff that breaks this; I'm going to push some commits to fix it so it can be merged. |
4aa7530 to
0ccdae1
Compare
|
for posterity: there was an internal concern about generating this on every invocation of |
This comment was marked as spam.
This comment was marked as spam.
|
While I'm still in favor of merging this as it's very useful from the command line ( I see three options:
I'm leaning towards the first option; in general the help topic system is meant to do double duty of CLI and HTML help and we're only going to want more markdown formatting in help topics, not less. I'm happy to augment this to output markdown. |
|
I've gotten this generating markdown in my local environment, but some shortcomings of glamour are making the output less than ideal; the primary issue is the inability to manually linebreak which I'd like for the flag usage lists. I'll explore using tables or blockquotes for that. Either way I have to focus on other things today but I'll circle back to this. |
|
I've pushed commits for having this output markdown. I had to make some trade-offs but I think it looks acceptable; most importantly, it should look ok on the manual website.
|
changes made, then i worked a lot on the PR
- the `<...>` characters from command usage line are now preserved by enclosing the entire usage synopsis in a code span - hard breaks in flag usage lines are preserved by enclosing flag usage in a code block - TTY detection and Markdown rendering are now delayed until the user explicitly requests `gh help reference` - `gh help reference` output is now pager-enabled
There was a problem hiding this comment.
Great work everyone!
I've pushed some changes to simplify things and add PAGER support. This is how gh reference looks now:
I've avoided Markdown issues around <...> and line breaks by wrapping those sections in <code> spans or blocks. Particularly, FlagUsages() output should be rendered in a code block due to its output currently being vertically-aligned.
When stdout is not a terminal, the reference command outputs no color. Similarly, no Markdown rendering or terminal detection happens when initializing the reference command, since that would add to the overhead of executing any gh command. Instead, rendering and detecting terminal features now only happens if the reference output was actually requested.
@vilmibm @samcoe When rebasing my changes onto this branch, I've removed the Static/DynamicHelpTopic distinction in the cleanup. It didn't feel that right now we need to maintain that distinction, since each of the functions had precisely 1 caller. It was also relatively easy to implement this with our original NewHelpTopic() function without any modifications.
| cmdutil.DisableAuthCheck(cmd) | ||
|
|
||
| // this needs to appear last: | ||
| referenceCmd.Long = referenceLong(cmd) |
There was a problem hiding this comment.
I dislike this approach but don't see value in further back and forthing on this given that we only have two help topics
|
|
||
| _ = io.StartPager() | ||
| defer io.StopPager() | ||
| fmt.Fprint(io.Out, md) |
There was a problem hiding this comment.
good thinking.
the environment help topic is also long and i assume future help topics will also be greater than one "page" (which seems to be the point of them) so we might want to consider always running the pager for help topics in the future
Hello! I tried to keep the reference simple and in line with the manual. Let me know if I need to change anything!
Closes #1734