Update agent cli reference docs generation #2406
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Certain help text in the agent will display the user's home directory as part of a default value. But this does not make sense in the docs.
Now, we will encase code blocks in `shell` backtick blocks. In the input, we will use 2 spaces for indentation, and we will use 4 spaces to indicate the start of a code block. We also substitute prime symbols in more places. And we will prevent the user's home directory from leaking into the docs via this script.
Previously, there was a state machine that was controlled by 2 boolean variables. But there were only 3 valid states. Now, because the state machine is explicit, we can avoid the invalid state.
Contributor
|
Preview URL: https://2406--bk-docs-preview.netlify.app |
triarius
force-pushed
the
pdp-1465-fix-docs-script-that-parses-agent-help-text
branch
from
99fea56 to
9c0af63
Compare
mbelton-buildkite
approved these changes
Aug 23, 2023
triarius
commented
Aug 23, 2023
| # Replace all prime symbols with backticks. We use prime symbols instead of backticks in CLI | ||
| # helptext because Go does not support escaping backticks in backtick delimited strings. | ||
| # See: https://github.com/buildkite/agent/blob/main/clicommand/prime-signs.md | ||
| line.tr!("′", "`") |
Contributor
Author
There was a problem hiding this comment.
Woah, my browser is not rendering this very well, but you should be able to copy this into your text editor and see that is prime sign.
moskyb
requested changes
Aug 23, 2023
scripts/cli2md.rb
Outdated
| ARGF.each_with_index do |line, line_num| | ||
| # Headings | ||
| # Replace all prime symbols with backticks. We use prime symbols instead of backticks in CLI | ||
| # helptext because Go does not support escaping backticks in backtick delimited strings. |
Contributor
There was a problem hiding this comment.
because Go does not support escaping backticks in backtick delimited strings
this is true, but not why we avoid backticks in usage strings; we actually avoid them because urfave/cli has special handling for backtick-enclosed substrings in usage docs, and mangles usage strings that have backticked strings in them
Contributor
There was a problem hiding this comment.
admittedly i probably could have put that there instead of just writing "reasons"
triarius
force-pushed
the
pdp-1465-fix-docs-script-that-parses-agent-help-text
branch
from
d7423a9 to
bda8578
Compare
moskyb
approved these changes
Aug 23, 2023
triarius
deleted the
pdp-1465-fix-docs-script-that-parses-agent-help-text
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is the script
cli2md.rbthat generates the agent cli reference docs.Its input is the output of
buildkite-agentcommands with the flag--help.We've changed some of the practices since when this script was first written. Now:
shellbacktick blocks. In the input, we will use 4 spaces to indicate the start of a code block.There is a companion PR to adjust the cli commands in the agent to work consistently with this script. If you checkout that version of the agent, compile it and run
scripts/update-agent-help.sh, it should be a no-op.