From d1f56429a75a5b47a47e12cf6adfb0628f300fdf Mon Sep 17 00:00:00 2001 From: Preeti Chandrashekar Date: Wed, 17 Sep 2025 16:03:41 +0530 Subject: [PATCH 1/2] add guidance on expalining commands and variables --- .../style_guidelines/code-commands.adoc | 2 +- .../style_guidelines/formatting.adoc | 111 ++++++++++++++++++ 2 files changed, 112 insertions(+), 1 deletion(-) diff --git a/supplementary_style_guide/style_guidelines/code-commands.adoc b/supplementary_style_guide/style_guidelines/code-commands.adoc index bc62ea21..1acd66bf 100644 --- a/supplementary_style_guide/style_guidelines/code-commands.adoc +++ b/supplementary_style_guide/style_guidelines/code-commands.adoc @@ -116,7 +116,7 @@ Reserved MAC addresses for documentation are defined in link:https://www.rfc-edi [[long-code-examples]] == Long code examples -All code blocks (regardless of length) must be necessary, accurate, and helpful. Code blocks must be as copy-and-paste friendly as possible, with the exception of variables and callouts. The length of the block is irrelevant, within reason, if the code block follows these guidelines. +All code blocks (regardless of length) must be necessary, accurate, and helpful. Code blocks must be as copy-and-paste friendly as possible, with the exception of variables. The length of the block is irrelevant, within reason, if the code block follows these guidelines. [[code-example-syntax-highlighting]] == Syntax highlighting diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index 642716b8..c3ef5399 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -50,6 +50,111 @@ default active yes yes For commands and command outputs in code blocks, observe the correct markup for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[]. +[[explain-commands-variables-in-code-blocks]] +== Explain commands and vairables in code blocks + +To explain commands, lines of code, or variables (user-replaced values) used in a code block, follow the code block with the relevant explanation or description of the elements. + +. Use a simple sentence to explain or describe a single line of command, variable, option, or parameter. ++ +.Example AsciiDoc: A simple sentence explainging a single coomand ++ +[source,terminal] +---- +$ hcp create cluster --help +---- ++ +You can use the `hcp create cluster` command to create and manage hosted clusters. The supported platforms are `aws`, `agent`, and `kubevirt`. ++ +. Use a bulleted list to describe the structure of a sample YAML file or explain multiple lines of code in a code block. +** List the explanations in the order in which they appear in the code block. ++ +.Example AsciiDoc: A bulleted list explaining the structure of an YAML file + +[source,yaml] +---- +apiVersion: tekton.dev/v1 +kind: Pipeline +metadata: + name: build-and-deploy +spec: + workspaces: + - name: shared-workspace + params: +... + tasks: + - name: build-image + taskRef: + resolver: cluster + params: + - name: kind + value: task + - name: name + value: buildah + - name: namespace + value: openshift-pipelines + workspaces: + - name: source + workspace: shared-workspace + params: + - name: TLSVERIFY + value: "false" + - name: IMAGE + value: $(params.IMAGE) + runAfter: + - fetch-repository + - name: apply-manifests + taskRef: + name: apply-manifests + workspaces: + - name: source + workspace: shared-workspace + runAfter: + - build-image +... +---- + +* `workspaces`: List of pipeline workspaces shared between the tasks defined in the pipeline. A pipeline can define as many workspaces as required. In this example, only one workspace named `shared-workspace` is declared. +* `tasks`: Definition of tasks used in the pipeline. This snippet defines two tasks, `build-image` and `apply-manifests`. +* `tasks.name.workspaces`: List of task workspaces used in the `build-image` and `apply-manifests` tasks. A task definition can include as many workspaces as it requires. However, it is recommended that a task uses at most one writable workspace. In this example, both the tasks share a common task workspace named `source`, which in turn shares the pipeline workspace named `shared-workspace`. + +. Use a definition list to explain multiple options, parameters, variables, placeholders, or UI elements. +** List the parameters/variables in the order in which they appear in the code block. +** Introduce definition lists with "where:" and begin each variable description with "Specifies". ++ +.Example AsciiDoc: A definition list explaining user-replaced values + +[source,yaml,subs="+attributes,+quotes"] +---- +cat < +type: Opaque +stringData: + postgres-ca.pem: |- + -----BEGIN CERTIFICATE----- + + postgres-key.key: |- + -----BEGIN CERTIFICATE----- + + postgres-crt.pem: |- + -----BEGIN CERTIFICATE----- + + # ... +EOF +---- ++ +where: + +:: Specifies the name of the certificate secret. +:: Specifies the CA certificate key. + Optional:: Specifies the TLS private key. + Optional:: Specifies the TLS certificate key. + +. Use the appropriate admonition style to add notes pertaining to a code block, as described in xref:admonitions[]. + [[date-formats]] == Date formats @@ -244,6 +349,9 @@ connection.interface-name: enp7s0 ---- ==== +To explain user replaced values used in a code block, you must use a definition list following the code block. See xref:explain-commands-variables-in-code-blocks[] for details. + + [[user-replaced-values-xml]] == User-replaced values for XML @@ -289,5 +397,8 @@ This example renders as follows in HTML: ---- ==== +To explain user replaced values used in a code block, you must use a definition list following the code block. See xref:explain-commands-variables-in-code-blocks[] for details. + + // TODO: Add new style entries alphabetically in this file From 5d34ac677034e041011df2a786422d7f475cb614 Mon Sep 17 00:00:00 2001 From: Preeti Chandrashekar Date: Thu, 18 Sep 2025 14:51:20 +0530 Subject: [PATCH 2/2] minor changes --- .../style_guidelines/formatting.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/supplementary_style_guide/style_guidelines/formatting.adoc b/supplementary_style_guide/style_guidelines/formatting.adoc index c3ef5399..2b099958 100644 --- a/supplementary_style_guide/style_guidelines/formatting.adoc +++ b/supplementary_style_guide/style_guidelines/formatting.adoc @@ -51,20 +51,20 @@ default active yes yes For commands and command outputs in code blocks, observe the correct markup for user-replaced values, as described in xref:user-replaced-values[] and xref:user-replaced-values-xml[]. [[explain-commands-variables-in-code-blocks]] -== Explain commands and vairables in code blocks +== Explain commands and variables in code blocks To explain commands, lines of code, or variables (user-replaced values) used in a code block, follow the code block with the relevant explanation or description of the elements. . Use a simple sentence to explain or describe a single line of command, variable, option, or parameter. + -.Example AsciiDoc: A simple sentence explainging a single coomand +.Example AsciiDoc: A simple sentence explaining a single coomand + [source,terminal] ---- $ hcp create cluster --help ---- + -You can use the `hcp create cluster` command to create and manage hosted clusters. The supported platforms are `aws`, `agent`, and `kubevirt`. +Use the `hcp create cluster` command to create and manage hosted clusters. The supported platforms are `aws`, `agent`, and `kubevirt`. + . Use a bulleted list to describe the structure of a sample YAML file or explain multiple lines of code in a code block. ** List the explanations in the order in which they appear in the code block. @@ -349,7 +349,7 @@ connection.interface-name: enp7s0 ---- ==== -To explain user replaced values used in a code block, you must use a definition list following the code block. See xref:explain-commands-variables-in-code-blocks[] for details. +To explain user-replaced values used in a code block, you must use a definition list following the code block. See xref:explain-commands-variables-in-code-blocks[] for details. [[user-replaced-values-xml]] @@ -397,7 +397,7 @@ This example renders as follows in HTML: ---- ==== -To explain user replaced values used in a code block, you must use a definition list following the code block. See xref:explain-commands-variables-in-code-blocks[] for details. +To explain user-replaced values used in a code block, you must use a definition list following the code block. See xref:explain-commands-variables-in-code-blocks[] for details.