Shell code snippets include command prompt

[sftim]

This is a...

• Feature Request
• Bug Report

Problem:
As per the current style guide, snippets of code shouldn't include the command prompt. On several pages there are code snippets that do include a prompt.

In some places this is mixed in with output, eg (Markdown):

```shell
$ printf "%s\n" "Foo bar"
Foo bar
```

Proposed Solution:
So, the style guide is clear. I'll amend the issue description.
I think a mixture of approaches.

We want to be able to show what to type mixed with sample output. So the style guide should cover that case and explain what to do.
The site generator might need changes to handle highlighting those blocks, treating the initial $ as a hint that the rest of the line is code, and lines not starting with $ as unformatted command output.

Once those changes are made we can go in and PR fixes to use the new style consistently.
Follow style guide: separate commands from output.

[DanyC97]

@sftim can you provide an example of type mixed with sample output ?

[sftim]

Ah, sorry. I edited that out whilst drafting @DanyC97

I've updated the issue description.

[sftim]

The pages that I think need fixing (en-US locale) are:

• https://kubernetes.io/docs/concepts/cluster-administration/certificates/
• https://kubernetes.io/docs/concepts/cluster-administration/logging/
• https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/
• https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/
• https://kubernetes.io/docs/concepts/configuration/secret/
• https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
• https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/
• https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
• https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
• https://kubernetes.io/docs/concepts/services-networking/connect-applications-service/
• https://kubernetes.io/docs/concepts/storage/volumes/
• https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
• https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/
• https://kubernetes.io/docs/concepts/workloads/controllers/replicationcontroller/
• https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
• https://kubernetes.io/docs/getting-started-guides/ubuntu/networking/
• https://kubernetes.io/docs/reference/access-authn-authz/authorization/
• https://kubernetes.io/docs/reference/kubectl/docker-cli-to-kubectl/
• https://kubernetes.io/docs/reference/kubectl/jsonpath/
• https://kubernetes.io/docs/reference/kubectl/overview/
• https://kubernetes.io/docs/setup/minikube/
• https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/
• https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/
• https://kubernetes.io/docs/tasks/administer-cluster/configure-multiple-schedulers/
• https://kubernetes.io/docs/tasks/administer-cluster/highly-available-master/
• https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/
• https://kubernetes.io/docs/tasks/administer-cluster/namespaces/
• https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/
• https://kubernetes.io/docs/tasks/administer-cluster/network-policy-provider/cilium-network-policy/
• https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/
• https://kubernetes.io/docs/tasks/administer-cluster/sysctl-cluster/
• https://kubernetes.io/docs/tasks/debug-application-cluster/debug-application/
• https://kubernetes.io/docs/tasks/debug-application-cluster/debug-service/
• https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/
• https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/
• https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/
• https://kubernetes.io/docs/tasks/federation/federation-service-discovery/
• https://kubernetes.io/docs/tasks/inject-data-application/podpreset/
• https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/
• https://kubernetes.io/docs/tasks/job/coarse-parallel-processing-work-queue/
• https://kubernetes.io/docs/tasks/job/fine-parallel-processing-work-queue/
• https://kubernetes.io/docs/tasks/job/parallel-processing-expansion/
• https://kubernetes.io/docs/tasks/run-application/configure-pdb/
• https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/
• https://kubernetes.io/docs/tasks/run-application/rolling-update-replication-controller/
• https://kubernetes.io/docs/tutorials/clusters/apparmor/

[iamneha]

I would like to submit PR for this issue

/assign @iamneha

[k8s-ci-robot]

@iamneha: GitHub didn't allow me to assign the following users: iamneha.

Note that only kubernetes members and repo collaborators can be assigned and that issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

I would like to submit PR for this issue

/assign @iamneha

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[DanyC97]

@iamneha before fire any PRs, could you please detail how you planning to tackle, maybe a PR on the style guide docs and a PR example will be okay.

Doing so then @sftim, myself or anyone else can pick it up and make sure that we are coordinating on the effort

[iamneha]

@sftim @DanyC97 I created a PR, please check here #12779
This is a reference PR so that it would be easy to review

If this looks fine I'll add commit for rest of the files as well

[zacharysarah]

@sftim 👋

We want to be able to show what to type mixed with sample output. So the style guide should cover that case and explain what to do.

Do we? Right now, the style guide specifies to separate commands from output. Or do you mean something different?

The site generator might need changes to handle highlighting those blocks, treating the initial $ as a hint that the rest of the line is code, and lines not starting with $ as unformatted command output.

Again, the style guide is clear about separating commands from output.

That said, there is a possibility for improvement where we offer examples in multiple languages: better implementation of shortcodes for tabs. I haven't seen any discussion of them so far, so wanted to raise visibility as a possible path for improvement.

[sftim]

Separate commands from output makes sense to me. I missed that when I was reading through before.

So, the style guide is clear. I'll amend the issue description.

[iamneha]

hi @sftim as you mentioned separate commands from output will work and you updated the description as well.
I want to open this issue again #12779 and I had already done these changes in my PR.
It would be very helpful if you look into it.

@zacharysarah @Rajakavitha1 can you open this #12779 issue again

[iamneha]

@sftim @DanyC97 I followed PR #12793 , #12794 , and #12798
I noticed only $ is removed from these PR and Separate commands from output is still not fixed

The pages that are partially fixed:

1. PR Update the fine-parallel-processing-work-queue.md task file to remove $ and remvoe text not appropiate for end user #12793
   Page fixed - content/en/docs/tasks/job/fine-parallel-processing-work-queue.md
2. PR Update the parallel-processing-expansion.md task file and remove $ #12794
   Page fixed - content/en/docs/tasks/job/parallel-processing-expansion.md
3. PR Update debug-service.md's tasks file to remove $ from kubectl and turn questions into bullet list #12798
   Page fixed - content/en/docs/tasks/debug-application-cluster/debug-service.md

I also think we do not need 1PR for 1 page.
We can submit all the changes in one PR

[DanyC97]

@iamneha you might have seen that i went ahead and updated all the pages to remove $

Once that is done i can either update the above PRs or vice-versa (rebase the PRs ).

regarding Separate commands from output i haven't touched it yet, i can do in the above PRs or 1 big one, i don't mind really.

At this point in time i think i need to rethink the strategy on how to fix everything i had in mind because the reality is:

a) there are fewer people with review/ approve permission who are available / can stay on top of all this and pair with me so we can deliver faster this changes
b) because of that it might take a very long time and that is not good either, even for cosmetic with no huge UX impact