Merge pull request #5127 from gaurav-nelson/source_tag_guidelines_update

Updated guidelines to include source tags before code blocks

Author: Gaurav Nelson

contributing_to_docs/doc_guidelines.adoc

@@ -404,39 +404,50 @@ configuration file represent, then use callouts to provide that information.
 
 Follow these general guidelines when using code blocks:
 
-* Do NOT show replaceables within code blocks.
-
 * Do NOT use any markup in code blocks; code blocks generally do not accept any markup.
 
-* Try to use callouts to provide information on what the output represents when required.
-
-For all code blocks, you must include an empty line above a code block.
-
+* For all code blocks, you must include an empty line above a code block.
++
 Acceptable:
-
++
 ....
 Lorem ipsum
 
 ----
 $ lorem.sh
 ----
 ....
-
++
 Not acceptable:
-
++
 ....
 Lorem ipsum
 ----
 $ lorem.sh
 ----
 ....
-
++
 Without the line spaces, the content is likely to be not parsed correctly.
 
-Use this format when embedding callouts into the code block:
+* It is recommended to include source tags for the programming language used in the code block to enable syntax highlighting. For example, use the source tags
+ `[source, bash]`, `[source, yaml]`, `[source, javascript]`.
++
+....
+Lorem ipsum
 
+[source, bash]
+----
+$ lorem.sh
+----
+....
+
+* Try to use callouts to provide information on what the output represents when required.
++
+Use this format when embedding callouts into the code block:
++
 [subs=-callouts]
 ....
+[source, bash]
 ----
 code example 1 <1>
 code example 2 <2>
@@ -445,17 +456,17 @@ code example 2 <2>
 <2> A note about the second example value.
 ....
 
-For long lines of code that you want to break up among multiple lines, use a
+* For long lines of code that you want to break up among multiple lines, use a
 backslash to show the line break. For example:
-
++
+[source, bash]
 ----
 $ oc get endpoints --all-namespaces --template \
     '{{ range .items }}{{ .metadata.namespace }}:{{ .metadata.name }} \
     {{ range .subsets }}{{ range .addresses }}{{ .ip }} \
     {{ end }}{{ end }}{{ "\n" }}{{ end }}' | awk '/ 172\.30\./ { print $1 }'
 ----
 
-
 === Inline Code or Commands
 Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.
 
@@ -478,17 +489,19 @@ To markup command syntax, use the code block and wrap the replaceables in <> wit
 ....
 The following command returns a list of objects for the specified object type:
 
+[source, bash]
 ----
-oc get <object_type> <object_id>
+$ oc get <object_type> <object_id>
 ----
 ....
 
 This would render as follows:
 
 The following command returns a list of objects for the specified object type:
 
+[source, bash]
 ----
-oc get <object_type> <object_id>
+$ oc get <object_type> <object_id>
 ----
 
 ==== Examples
@@ -499,33 +512,31 @@ As mentioned an example of a command should use actual values and also show an o
 In the following example the `oc get` operation returns a complete list of services that are currently defined.
 
 .Example Title
-====
 
+[source, bash]
 ----
 $ oc get se
 NAME                LABELS                                    SELECTOR            IP                  PORT
 kubernetes          component=apiserver,provider=kubernetes   <none>              172.30.17.96        443
 kubernetes-ro       component=apiserver,provider=kubernetes   <none>              172.30.17.77        80
 docker-registry     <none>                                    name=registrypod    172.30.17.158       5001
 ----
-====
 ....
 
 This would render as shown:
 
 In the following example the `oc get` operation returns a complete list of services that are currently defined.
 
 .Example Title
-====
 
+[source, bash]
 ----
 $ oc get se
 NAME                LABELS                                    SELECTOR            IP                  PORT
 kubernetes          component=apiserver,provider=kubernetes   <none>              172.30.17.96        443
 kubernetes-ro       component=apiserver,provider=kubernetes   <none>              172.30.17.77        80
 docker-registry     <none>                                    name=registrypod    172.30.17.158       5001
 ----
-====
 
 === Lists
 Lists are created as shown in this example: