Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: yaml artifacts in guides should code-highlight #3137

Closed
eitansuez opened this issue Apr 8, 2024 · 6 comments · Fixed by #3223
Closed

docs: yaml artifacts in guides should code-highlight #3137

eitansuez opened this issue Apr 8, 2024 · 6 comments · Fixed by #3223
Assignees
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers

Comments

@eitansuez
Copy link
Contributor

Description:

most of the tasks combine [a] displaying yaml to be applied with [b] applying it to the cluster using the shorthand:

cat <<EOF | kubectl apply -f -
---
some: yaml
EOF

this is great and convenient copy-paste.
but if the resources were presented first as bona-fide yaml, you'd get better yaml highlighting/color-coding, which makes it easier for the reader to review the content.
it also gives the reader an opportunity to copy just the yaml if they want to save these CRs on their file system and study them before doing a kubectl apply.
(also if the reader is not using the bash shell, that command might not work)

suggestion: revise all instructions in the user guides / tasks such that we display yaml instead, along with an instruction to kubectl apply the resource[s] to the cluster:

---
some: yaml
@shawnh2 shawnh2 added documentation Improvements or additions to documentation good first issue Good for newcomers help wanted Extra attention is needed and removed triage labels Apr 9, 2024
@yuluo-yx
Copy link
Contributor

yuluo-yx commented Apr 9, 2024

/assign @yuluo-yx

@shawnh2 shawnh2 removed the help wanted Extra attention is needed label Apr 9, 2024
@eitansuez
Copy link
Contributor Author

fyi, i have an implementation i'll submit shortly via a PR.

@yuluo-yx yuluo-yx removed their assignment Apr 9, 2024
@yuluo-yx
Copy link
Contributor

yuluo-yx commented Apr 9, 2024

fyi, i have an implementation i'll submit shortly via a PR.

got it.

eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 9, 2024
…ctl apply -f - <<EOF part (envoyproxy#3137)

Signed-off-by: Eitan Suez <eitan@tetrate.io>
@arkodg
Copy link
Contributor

arkodg commented Apr 9, 2024

hey @eitansuez, can we also support applying via STDIN ? maybe using a tab view ? so the user doesn't need to think about saving and applying ?

@eitansuez
Copy link
Contributor Author

that's a good idea. let me work on that..

@eitansuez
Copy link
Contributor Author

waiting on tabs capability to get merged, and then the plan will be to display two tabs - one with a command to apply the resource directly to the cluster, the other provides just the resource that a user can copy and save to a file before applying.

eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 19, 2024
…file using tabs

Signed-off-by: Eitan Suez <eitan@tetrate.io>
eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 19, 2024
…ets using tabs

Signed-off-by: Eitan Suez <eitan@tetrate.io>
eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 19, 2024
…inting

Signed-off-by: Eitan Suez <eitan@tetrate.io>
eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 23, 2024
…file using tabs

Signed-off-by: Eitan Suez <eitan@tetrate.io>
eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 23, 2024
…ets using tabs

Signed-off-by: Eitan Suez <eitan@tetrate.io>
eitansuez pushed a commit to eitansuez/gateway that referenced this issue Apr 23, 2024
…inting

Signed-off-by: Eitan Suez <eitan@tetrate.io>
zirain pushed a commit that referenced this issue Apr 24, 2024
#3223)

* docs: (#3137) show 'apply yaml' either from stdin, or from file using tabs

Signed-off-by: Eitan Suez <eitan@tetrate.io>

* docs: (#3137) retrofit remaining 'kubectl apply' yaml snippets using tabs

Signed-off-by: Eitan Suez <eitan@tetrate.io>

* docs: (#3137) surrounds shell blocks with blank lines for linting

Signed-off-by: Eitan Suez <eitan@tetrate.io>

---------

Signed-off-by: Eitan Suez <eitan@tetrate.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers
Projects
None yet
4 participants