Rework Hammer reference generation (#4234)

Co-authored-by: Maximilian Kolb <[email protected]>

Author: Lennonka

guides/doc-Hammer_Reference/README.md

@@ -1,16 +1,40 @@
-# Generated Hammer reference
+# Creating Hammer reference
 
-Use the `generate-hammer-reference.sh` script to update the generated reference.
+## Generating the reference
 
-## Prerequisite
+Use the `generate-hammer-reference.sh` script to generate the reference.
 
+### Prerequisites
+
+- Ensure all Foreman plugins are enabled on your Foreman instance.
 - You have got the full help output from Hammer CLI in MarkDown format:
   ```
      hammer full-help --md >hammer.full-help.md
   ```
 
-## Usage
+### Usage
 ```
    cd guides/
+   mkdir --parents common/hammer-reference
    scripts/generate-hammer-reference.sh hammer.full-help.md
 ```
+
+## Manual editing
+
+Move `content-view component` and `content-view filter` sections, which are level 3 and have level 4 sections, to **level 2** to decrease section nesting to 3 levels.
+
+Generated structure:
+```
+2.1 content-view
+   2.1.x content-view component
+   2.1.y content-view filter
+2.2 content-view-environment
+```
+
+Manually updated structure:
+```
+2.1 content-view
+2.2 content-view component
+2.3 content-view-environment
+2.4 content-view filter
+```

guides/scripts/generate-hammer-reference.sh

@@ -1,16 +1,16 @@
 #!/usr/bin/bash
 
 SRC=
-ASMB_DIR=common # assembly destination folder
-MOD_DIR=modules
+MOD_DIR=common/hammer-reference/
 MOD_TYPE=":_mod-docs-content-type: REFERENCE"
-ASMB_FILENAME=assembly_hammer-reference.adoc
+ROLE_ABSTRACT='[role="_abstract"]'
+ASMB_FILENAME=doc-Hammer_Reference/master.adoc
 NOOP= # dry run
 DEBUG=
 
 print_help() {
     echo -e "Generate AsciiDoc reference from a Hammer full-help MarkDown file"
-    echo -e "  Generates one assembly and one module per hammer command."
+    echo -e "Generates $ASMB_FILENAME and one module per hammer subsubcommand (3 levels)."
     echo
     echo -e "Usage:"
     echo -e "    $0 [OPTIONS ...] SOURCE_FILE"
@@ -19,9 +19,8 @@ print_help() {
     echo
     echo -e "Options:"
     echo -e "  --target-dir, -T DIR"
-    echo -e "               Path to a folder where the reference assembly"
-    echo -e "               will be placed. Default: $ASMB_DIR"
-    echo -e "               Modules will be placed in $ASMB_DIR/$MOD_DIR/"
+    echo -e "               Path to a folder where the reference modules"
+    echo -e "               will be placed. Default: $MOD_DIR"
     echo -e "  --help, -h   Print help and exit"
     echo -e "  --noop       Dry run (don't do anything, only preview output)"
     echo -e "  --debug, -d  Debug mode (verbose output and keep tmp file)"
@@ -37,10 +36,10 @@ bye() {
 
 # Process user arguments
 if [ $# -eq 0 ]; then print_help; exit 1; fi
-while [ $# -gt 1 ]; do
+while [ $# -gt 0 ]; do
     case "$1" in
         --target-dir|-T)
-            ASMB_DIR="$2"
+            MOD_DIR="$2"
             shift 2
             ;;
         --noop)
@@ -64,32 +63,37 @@ while [ $# -gt 1 ]; do
             print_help
             exit 0
             ;;
-        *)
+        -*)
             bye "E: Invalid option: $1"
             ;;
+        *)
+            break
     esac
 done
 SRC=$1
 
-# Define internal variables
-if [ -n "$ASMB_DIR" ]; then
-    mod_path=$ASMB_DIR/$MOD_DIR # module destination folder
-    asmb_file=$ASMB_DIR/$ASMB_FILENAME
-else
-    mod_path=$MOD_DIR
-    asmb_file=$ASMB_FILENAME
+# Exit if source file doesn't exist
+if [ ! -f "$SRC" ]; then
+    bye "E: Source file not found: $SRC"
 fi
+
+# Define internal variables
+mod_path=${MOD_DIR%/}
+asmb_file=$ASMB_FILENAME
 details_tmp="$mod_path/tmp_hammer-option-details"
-echo -e >$details_tmp # reset
 
-details_file="$mod_path/ref_hammer-option-details.adoc"
-details_header='[id="hammer-option-details"]\n= Option details\n\nHammer options accept the following option types and values:'
+details_file="$mod_path/ref_data-representation-in-hammer-options.adoc"
+details_header="$MOD_TYPE\n\n[id="data-representation-in-hammer-options"]\n= Data representation in Hammer options\n\n$ROLE_ABSTRACT\nHammer options accept the following types and values."
 
-asmb_header=':_mod-docs-content-type: ASSEMBLY\n\n// DO NOT EDIT MANUALLY\n// Use the generate-hammer-reference.sh script to update\n\ninclude::modules/con_hammer-reference.adoc[]\n\n'
-asmb_footer='include::modules/ref_hammer-option-details.adoc[leveloffset=+1]\n'
+asmb_header="include::common/attributes.adoc[]\ninclude::common/header.adoc[]\n:context: hammer-reference\n:hammer-reference:\n\n= {HammerRefDocTitle}\n\nifdef::satellite[]\ninclude::common/modules/proc_providing-feedback-on-red-hat-documentation.adoc[leveloffset=+1]\nendif::[]\n\n// DO NOT EDIT MANUALLY!\n// Use the generate-hammer-reference.sh script to update\n\ninclude::$mod_path/ref_data-representation-in-hammer-options.adoc[leveloffset=+1]\n"
+asmb_footer='ifndef::orcharhino,satellite[]\ninclude::common/ribbons.adoc[]\nendif::[]\n'
 
-# Create folders
-{ [ -n "$NOOP" ] || mkdir -p $mod_path ; } && echo -e "Created folders: " $mod_path
+# Exit if module path doesn't exist
+if [ -d "$mod_path" ]; then
+    echo "I: Module path exists: $mod_path"
+else
+    bye "E: Module path not found: $mod_path"
+fi
 
 # Output headers
 if [ -z "$NOOP" ]; then
@@ -98,8 +102,7 @@ if [ -z "$NOOP" ]; then
 fi
 if [ -z "$ASSEMBLY_ONLY" ]; then
     echo -e "$details_header" >$details_file && \
-        { [ -n "$DEBUG" ] && echo -e "I: Option details header written" ; } || \
-        echo -e "W: Something went wrong writing option details header"
+        [ -n "$DEBUG" ] && echo -e "I: Data representation header written"
 fi
 
 # Read lines from the source file
@@ -115,31 +118,31 @@ cat "$SRC" | while read line ; do
         '- ['*) # Skip MD TOC
             continue
         ;;
-        "# hammer") # top-command
+        "# hammer") # program
             echo -e "I: [cmd-1]: $line"
             id_core=hammer
             mod_file="$mod_path/ref_$id_core.adoc"
             id='[id="hammer"]'
             heading='= hammer'
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e "$MOD_TYPE\n\n$id\n$heading" >$mod_file
+                echo -e -n "$MOD_TYPE\n\n$id\n$heading\n\n$ROLE_ABSTRACT" >$mod_file
             { [ -z "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] ; } && \
-                echo -e "include::modules/ref_hammer.adoc[leveloffset=+1]\n" >>$asmb_file
+                echo -e "include::$mod_path/ref_hammer.adoc[leveloffset=+1]\n" >>$asmb_file
             begin_section=yes
             skip_section=
             continue
         ;;
         "## hammer"*) # command
             echo -e "I: [cmd-2]: $line"
             id_core=`echo -e $line | sed 's/^## //' | sed 's/ /-/g'`
-            filename=ref_$id_core.adoc
+            filename=ref_${id_core}.adoc
             mod_file="$mod_path/$filename"
-            id=[id=\"$id_core\"]
+            id=[id=\"${id_core}\"]
             heading=`echo -e $line | sed 's/^## hammer/=/'`
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e "$MOD_TYPE\n\n$id\n$heading" >$mod_file
+                echo -e -n "$MOD_TYPE\n\n$id\n$heading\n\n$ROLE_ABSTRACT" >$mod_file
             { [ -z "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] ; } && \
-                echo -e "include::modules/$filename[leveloffset=+1]\n" >>$asmb_file
+                echo -e "include::$mod_path/$filename[leveloffset=+1]\n" >>$asmb_file
             begin_section=yes
             skip_section=
             options=
@@ -152,10 +155,14 @@ cat "$SRC" | while read line ; do
         "### hammer"*) # subcommand
             [ -n "$DEBUG" ] && echo -e "I: [cmd-3]: $line"
             id_core=`echo -e $line | sed 's/^### //' | sed 's/ /-/g'`
-            id=[id=\"$id_core\"]
-            heading=`echo -e $line | sed 's/^### hammer/==/'`
+            id=[id=\"${id_core}\"]
+            filename=ref_${id_core}.adoc
+            mod_file="$mod_path/$filename"
+            heading=`echo -e $line | sed 's/^### hammer/=/'`
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e "$MOD_TYPE\n\n$id\n$heading" >>$mod_file
+                echo -e -n "$MOD_TYPE\n\n$id\n$heading\n\n$ROLE_ABSTRACT" >>$mod_file
+            { [ -z "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] ; } && \
+                echo -e "include::$mod_path/$filename[leveloffset=+2]\n" >>$asmb_file
             begin_section=yes
             skip_section=
             options=
@@ -168,10 +175,14 @@ cat "$SRC" | while read line ; do
         "#### hammer"*) # subsubcommand
             [ -n "$DEBUG" ] && echo -e "I: [cmd-4]: $line"
             id_core=`echo -e $line | sed 's/^#### //' | sed 's/ /-/g'`
-            id=[id=\"$id_core\"]
-            heading=`echo -e $line | sed 's/^#### hammer/===/'`
+            id=[id=\"${id_core}\"]
+            filename=ref_${id_core}.adoc
+            mod_file="$mod_path/$filename"
+            heading=`echo -e $line | sed 's/^#### hammer/=/'`
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e "$MOD_TYPE\n\n$id\n$heading" >>$mod_file
+                echo -e -n "$MOD_TYPE\n\n$id\n$heading\n\n$ROLE_ABSTRACT" >>$mod_file
+            { [ -z "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] ; } && \
+                echo -e "include::$mod_path/$filename[leveloffset=+3]\n" >>$asmb_file
             begin_section=yes
             skip_section=
             options=
@@ -184,10 +195,10 @@ cat "$SRC" | while read line ; do
         "##### hammer"*) # subsubsubcommand
             [ -n "$DEBUG" ] && echo -e "I: [cmd-5]: $line"
             id_core=`echo -e $line | sed 's/^##### //' | sed 's/ /-/g'`
-            id=[id=\"$id_core\"]
-            heading=`echo -e $line | sed 's/^##### hammer/====/'`
+            id=[id=\"${id_core}\"]
+            heading=`echo -e $line | sed 's/^##### hammer/==/'`
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e "$MOD_TYPE\n\n$id\n$heading" >>$mod_file
+                echo -e "$id\n$heading" >>$mod_file
             begin_section=yes
             skip_section=
             options=
@@ -200,7 +211,7 @@ cat "$SRC" | while read line ; do
         "Usage:")
             [ -n "$DEBUG" ] && echo -e "I: [Usage]ID: $id_core"
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e ".Usage" >>$mod_file
+                echo -e "*Usage*\n" >>$mod_file
             skip_section=
             continue
         ;;
@@ -223,15 +234,15 @@ cat "$SRC" | while read line ; do
         "Options:")
             [ -n "$DEBUG" ] && echo -e "I: [Options]ID: $id_core"
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e ".Options" >>$mod_file
+                echo -e "*Options*\n" >>$mod_file
             options=yes
             skip_section=
             continue
         ;;
         *"Predefined field sets"*)
             [ -n "$DEBUG" ] && echo -e "I: [Predefined field sets]ID: $id_core"
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e ".Predefined field sets" >>$mod_file
+                echo -e "*Predefined field sets*\n" >>$mod_file
             field_sets=yes
             table_delim=0
             skip_section=
@@ -249,7 +260,7 @@ cat "$SRC" | while read line ; do
         "Provider specific options:")
             [ -n "$DEBUG" ] && echo -e "I: [Provider specific options]ID: $id_core"
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e ".Provider specific options\n" >>$mod_file
+                echo -e "*Provider-specific options*\n" >>$mod_file
             provider_specific=yes
             skip_section=
             options=
@@ -260,7 +271,7 @@ cat "$SRC" | while read line ; do
         *Search*fields*)
             [ -n "$DEBUG" ] && echo -e "I: [Search / Order fields]ID: $id_core"
             [ -n "$NOOP" ] || [ -n "$ASSEMBLY_ONLY" ] || \
-                echo -e ".Search / Order fields" >>$mod_file
+                echo -e "*Search and order fields*\n" >>$mod_file
             search_fields=yes
             skip_section=
             options=
@@ -328,7 +339,7 @@ cat "$SRC" | while read line ; do
         fixed_line=`echo -e "$fixed_line" | sed -E 's/..1m|..0m/\*/g'` #bold
         if echo -e "${line}" | grep -Eq '^-{1,2}[a-z\[]' - ; then # option line
             fixed_line=`echo -e "$fixed_line" | sed -E 's/^(-[a-z])/\`\1\`/' | sed -E 's/( )(-[a-z])/\1\`\2\`/g'`
-            fixed_line=`echo -e "$fixed_line" | sed -E 's/(--\S+\s[A-Z\_]{3,})/\`\1\`/' | sed -E 's/([A-Z\_]{3,})(\`)/xref:hammer-option-details-\L\1\E\[\1\]\2/'`
+            fixed_line=`echo -e "$fixed_line" | sed -E 's/(--\S+\s[A-Z\_]{3,})/\`\1\`/' `
             fixed_line=`echo -e "$fixed_line" | sed -E 's/^(--\S+)/\`\1\`/' | sed -E 's/( )(--\S+)/\1\`\2\`/g'`
             fixed_line=`echo -e "$fixed_line" | sed -E 's/   +/ \{endash\} /'`
             fixed_line="* $fixed_line"
@@ -426,9 +437,9 @@ echo -e "I: [End of input file]"
 echo
 
 # Process option details
-echo -e "Processing option details..."
+echo -e "Processing data representation module..."
 sort $details_tmp | uniq | \
-    sed -E 's/^([A-Z\_]+)\s+/\n\[id="hammer-option-details-\L\1\E"\]\n\1:: /' >>$details_file
+    sed -E 's/^([A-Z\_]+)\s+/\n\1:: /' >>$details_file
 [ -n "$DEBUG" ] || rm $details_tmp # Delete tmp file
 
 echo