ENT-10940: file and command components in examples & web ui sections

.github/workflows/markdowner.py

@@ -3,6 +3,7 @@
 # find . -name '*.markdown' -type f -exec python3 .github/workflows/markdowner.py {} all \; | tee output.log
 
 import sys
+import re
 from collections import defaultdict
 
 
@@ -27,6 +28,14 @@ def replace_with_dict(content, replacements, filename):
     return content
 
 
+def replace_with_regex_dict(content, replacements, filename):
+    for k, v in replacements.items():
+        while re.search(k, content, flags=re.MULTILINE):
+            print(f"{filename}: {repr(k)} -> {repr(v)}")
+            content = re.sub(k, v, content, flags=re.MULTILINE)
+    return content
+
+
 def process_codeblock(lines, filename, lineno_start):
     result = []
     begin = lines[0]
@@ -184,6 +193,8 @@ def perform_edits(content, flags, filename):
             print(f"{filename}: Added newline before EOF")
 
     if flags.codeblocks or flags.all:
+        replacements = {r"(?<!\n)\n```command": "\n\n```command"}
+        content = replace_with_regex_dict(content, replacements, filename)
         content = edit_codeblocks(content, filename)
     return content
 

examples.markdown

@@ -51,6 +51,7 @@ Following these steps, you will login to your policy server via the SSH protocol
 5. In the vi editor, enter ```i``` for "Insert" and enter the following content (ie. copy and paste from a text editor):
 
     ```cf3
+   [file=hello_world.cf]
     bundle agent hello_world
     {
       reports:
@@ -78,21 +79,23 @@ hosts][Classes and decisions].
 
 Activate the bundle manually by executing the following command at prompt:
 
-```console
+```command
 /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world
 ```
 
 This command instructs CFEngine to ignore [locks][Controlling frequency], load
 the `hello_world.cf` policy, and activate the `hello_world` bundle. See the output below:
 
-```console
-# /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world
+```command
+/var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf --bundlesequence hello_world
+```
+```output
 2013-08-20T14:03:43-0500   notice: R: Hello World!
 ```
 
 As you get familiar with CFEngine, you'll probably start shortening this command to this equivalent:
 
-```console
+```command
 /var/cfengine/bin/cf-agent -Kf ./hello_world.cf -b hello_world
 ```
 
@@ -118,6 +121,7 @@ Go back into vi by typing "vi" at the prompt. Then type ```i``` to insert
 shown in the following example:
 
 ```cf3
+[file=hello_world.cf]
 body common control
 {
   bundlesequence => { "hello_world" };
@@ -138,20 +142,24 @@ Now press "esc" to exit the "Insert" mode, then type ```:w``` to save the file c
 Exit vi by typing ```:q``` then "Enter." This will return to the prompt.
 
 Execute the following command:
-```console
+
+```command
 /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf
 ```
 
 The output is shown below:
 
-```console
-# /var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf
+```command
+/var/cfengine/bin/cf-agent --no-lock --file ./hello_world.cf
+```
+```output
 2013-08-20T14:25:36-0500   notice: R: Hello World!
 ```
 
 Note: It may be necessary to add a reference to the standard library within the body common control section, and remove the bundlesequence line. Example:
 
 ```cf3
+[file=hello_world.cf]
 body common control {
     inputs => {
        "libraries/cfengine_stdlib.cf",
@@ -171,6 +179,7 @@ Again type "vi" then "Enter" then ```i``` to insert the following:
 Add it before __body common control__, as shown below:
 
 ```cf3
+[file=hello_world.cf]
 #!/var/cfengine/bin/cf-agent --no-lock
 body common control
 {
@@ -193,21 +202,19 @@ then exit vi by typing ```:q``` then "Enter". This will return to the prompt.
 
 Make the policy file executable, and then run it, by typing the following two commands:
 
-```console
+```command
 chmod +x ./hello_world.cf
 ```
 
 Followed by:
 
-```console
+```command
 ./hello_world.cf
 ```
 
 See the output below:
 
-```console
-# chmod +x ./hello_world.cf
-# ./hello_world.cf
+```output
 2013-08-20T14:39:34-0500   notice: R: Hello World!
 ```
 

examples/example-snippets/promise-patterns/example_aborting_execution.markdown

@@ -15,17 +15,21 @@ If any of these classes becomes defined, it will cause the current bundle to be
 
 This is how the policy runs when the userlist is valid:
 
-    # cf-agent -f unit_abort.cf
-    R: User name mark is valid at 4 letters
-    R: User name john is valid at 4 letters
-    #
-
+```command
+cf-agent -f unit_abort.cf
+```
+```output
+R: User name mark is valid at 4 letters
+R: User name john is valid at 4 letters
+```
 This is how the policy runs when the userlist contains an invalid entry:
 
-    # cf-agent -f unit_abort.cf
-    Bundle example aborted on defined class "invalid"
-    #
-
+```command
+cf-agent -f unit_abort.cf
+```
+```output
+Bundle example aborted on defined class "invalid"
+```
 To run this example file as part of your main policy you need to make an
 additional change:
 

examples/example-snippets/promise-patterns/example_change_detection.markdown

@@ -22,18 +22,22 @@ First, let's create some files for CFEngine to monitor:
 
 CFEngine detects new files and adds them to the file integrity database:
 
+```command
+cf-agent -f unit_change_detect.cf
 ```
-# cf-agent -f unit_change_detect.cf
+```output
 2013-06-06T20:53:26-0700    error: /example/files/'/etc/example':
 File '/etc/example/example.conf' was not in 'md5' database - new file found
-# cf-agent -f unit_change_detect.cf -K
+```
+
+```command
+cf-agent -f unit_change_detect.cf -K
 ```
 
 If there are no changes, CFEngine runs silently:
 
-```
-# cf-agent -f unit_change_detect.cf
-#
+```command
+cf-agent -f unit_change_detect.cf
 ```
 
 Now let's update the mtime, and then the mtime and content.

examples/example-snippets/promise-patterns/example_create_filedir.markdown

@@ -12,10 +12,11 @@ and set permissions on both.
 
 Example output:
 
+```command
+cf-agent -f unit_create_filedir.cf -I
 ```
-# cf-agent -f unit_create_filedir.cf -I
+```output
 2013-06-08T14:56:26-0700     info: /example/files/'/home/mark/tmp/test_plain': Created file '/home/mark/tmp/test_plain', mode 0640
 2013-06-08T14:56:26-0700     info: /example/files/'/home/mark/tmp/test_dir/.': Created directory '/home/mark/tmp/test_dir/.'
 2013-06-08T14:56:26-0700     info: /example/files/'/home/mark/tmp/test_dir/.': Object '/home/mark/tmp/test_dir' had permission 0755, changed it to 0750
-#
 ```

examples/example-snippets/promise-patterns/example_diskfree.markdown

@@ -12,11 +12,17 @@ Check how much space (in KB) is available on a directory's current partition.
 
 Example output:
 
+```command
+cf-agent -f unit_diskfree.cf
 ```
-# cf-agent -f unit_diskfree.cf
+```output
 R: Freedisk 48694692
-# df -k /tmp
+```
+
+```command
+df -k /tmp
+```
+```output
 Filesystem     1K-blocks     Used Available Use% Mounted on
 /dev/sda1      149911836 93602068  48694692  66% /
-#
 ```

examples/example-snippets/promise-patterns/example_edit_motd.markdown

@@ -30,8 +30,10 @@ The bundle is defined like this:
 
 **Example run:**
 
-```console
-root@debian8:~/core/examples# cf-agent -KIf ./mustache_template_motd.cf; cat /etc/motd
+```command
+cf-agent -KIf ./mustache_template_motd.cf; cat /etc/motd
+```
+```output
     info: Updated rendering of '/etc/motd' from mustache template 'inline'
     info: files promise '/etc/motd' repaired
 # Managed by CFEngine