cli: update nomad job init full examples #24232
Merged
Conversation
This file contains 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
aimeeu
added
theme/docs
aimeeu
approved these changes
Oct 17, 2024
There was a problem hiding this comment.
schmichael - Thanks for including me! Some style guide suggestions:
- changed "please see" to "refer to". We are not supposed to use "see"
- changed future tense to present tense
- changed passive voice to active voice where it made sense
I'll add a new page to the team-nomad wiki with the aforementioned style guidelines plus how to engage the docs team (which is currently in Confluence but the Eng team doesn't look there).
command/asset/example.nomad.hcl
Outdated
| # | ||
| # For more information and examples on the "template" block, please see | ||
| # the online documentation at: | ||
| # For more information and examples on the "template" block, please see: |
There was a problem hiding this comment.
Suggested change
| # For more information and examples on the "template" block, please see: | |
| # For more information and examples on the "template" block, refer to: |
command/asset/example.nomad.hcl
Outdated
| # and revocation of the Vault token. | ||
| # The "vault" block instructs the Nomad client to acquire a token from a | ||
| # HashiCorp Vault server. Nomad must be configured to communicate with | ||
| # Vault. By default, Nomad will inject the token into the task via an |
There was a problem hiding this comment.
Suggested change
| # Vault. By default, Nomad will inject the token into the task via an | |
| # Vault. By default, Nomad injects the token into the task via an |
command/asset/example.nomad.hcl
Outdated
| # The "vault" block instructs the Nomad client to acquire a token from a | ||
| # HashiCorp Vault server. Nomad must be configured to communicate with | ||
| # Vault. By default, Nomad will inject the token into the task via an | ||
| # environment variable and make the token available to the "template" |
There was a problem hiding this comment.
Suggested change
| # environment variable and make the token available to the "template" | |
| # environment variable and makes the token available to the "template" |
command/asset/example.nomad.hcl
Outdated
| # | ||
| # For more information and examples on the "vault" block, please see | ||
| # the online documentation at: | ||
| # For more information and examples on the "vault" block, please see: |
There was a problem hiding this comment.
Suggested change
| # For more information and examples on the "vault" block, please see: | |
| # For more information and examples on the "vault" block, refer to: |
Co-authored-by: Aimee Ukasick <[email protected]>
This was referenced Oct 17, 2024
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.
The full example jobspecs emitted by
nomad job initandnomad job init -connecthave not seen any improvement in over a year. I intended to just peek in, add a newui{}block block, and be done. However, something about skimming over the phrasethe online documentationa dozen times made me stop and do some spring cleaning.The diff is an absolute nightmare even though I think my changes are fairly minor. Some highlights:
uiblock because I think it should be a widely used feature!affinity{}.the online documentation. It is 2024, not 1999. I think our users know what a URL implies.affinity{}and all of its field comments, so I just removed the field comments. I think users are much better off visiting the online documentation for those details. The examples should demonstrate Nomad's featureset, not be a comprehensive guide to those features.Pinging @philrenaud because I've been pestering Phil with
ui{}things already, and @aimeeu because despite this being a part of thenomadbinary, I think it's documentation, and I want to make sure my changes fit with the style of similar examples our docs are full of. Let me know if you want to hand it off.