[Docs] Update "Alert and action settings" docs to be generated from YAML source

.github/CODEOWNERS

@@ -2512,6 +2512,9 @@ oas_docs/.spectral.yaml                       @elastic/platform-docs
 oas_docs/kibana.info.serverless.yaml          @elastic/platform-docs
 oas_docs/kibana.info.yaml                     @elastic/platform-docs
 
+# Documentation settings files
+docs/settings-gen                             @elastic/platform-docs
+
 # Plugin manifests
 /src/plugins/**/kibana.jsonc @elastic/kibana-core
 /x-pack/plugins/**/kibana.jsonc @elastic/kibana-core

docs/settings-gen/parse-settings.pl

@@ -0,0 +1,257 @@
+#!/usr/bin/perl
+
+# This little script finds any .yml files in the /source directory and, for each, generates an asciidoc file of the same name.
+# The output asciidoc file is a set of tagged regions, one for each configuration setting in the yaml file.
+# The tagged region can then be included in any Asciidoc file by means of an `include` statement. 
+# Run the script with:   perl parse-settings.pl
+# There are no parameters
+
+
+use strict;
+use warnings;
+use YAML::Tiny;
+use File::Find;
+use File::Copy;
+
+my $file;
+# I'm hardcoding these directories just temporarily for testing
+my $sourcedir = './source';
+my $asciidocdir = 'source/';
+my $count;
+
+find(\&iteratefiles, $sourcedir);
+print "\n\nProcessed ".$count. " files.\n";
+exit;
+
+sub iteratefiles {
+  $file = $_;
+  # ignore any non-yaml files
+  if (!($file =~ /\.yml$/)) {return;}
+  print "\nParsed file: ".$file;
+  my $testslice = parsefile($file);
+return;
+}
+
+sub parsefile {
+  # Create an output file based on yaml filename
+  my $outputfile = my $outputfileorig = $file;
+  $outputfile =~ s/.yml/.asciidoc/g;
+  # We'll use this to store the contents of the generated asciidoc file
+
+  # Read in the yaml file
+  my $yaml = YAML::Tiny->read( $file );
+
+  # Get a reference to the first document
+  #my $config = $yaml->[0];
+
+  my $collection = $yaml->[0]->{collection};
+  my $product = $yaml->[0]->{product};
+
+  # This variable is used to capture all the content that will become our output asciidoc file
+  my $asciidocoutput = "\n".'// '."This is a generated file; please don't update it directly.\n".'//'." Instead, the updatable source for these settings can be found in ".$outputfileorig;
+  $asciidocoutput .= "\n".'// '."Collection: ".$collection;
+  $asciidocoutput .= "\n".'// '."Product: ".$product."\n\n";
+
+  # build the page preamble paragraphs
+  my $page_description = $yaml->[0]->{page_description};
+  my $page_description_string = "";
+  for my $paragraph (@$page_description) {
+    $page_description_string .= $paragraph."\n\n";
+  }
+  # remove the + sign after the last paragraph of the description
+  if ($page_description_string) {
+    $page_description_string =~ s/\+$//;
+    chomp ($page_description_string);
+  }
+  if ($page_description_string) {
+    $asciidocoutput .= $page_description_string;
+  }
+
+
+
+
+  my $groups = $yaml->[0]{groups};
+  for my $group (@$groups) {
+
+    # Grab the group name, description, and other properties
+    my $group_id = $group->{id};
+    my $group_name = $group->{group};
+    my $group_description = $group->{description};
+    my $group_example = $group->{example};
+
+    # Add the group info to the asciidoc file contents
+    $asciidocoutput .= "\n\n";
+    if ($group_id) {
+      $asciidocoutput .= "[float]\n[[".$group_id."]]\n=== ".$group_name."\n\n";
+    }
+    else {
+      $asciidocoutput .= "[float]\n=== ".$group_name."\n\n";
+    } 
+    # build the group preamble paragraphs
+    my $group_description_string = "";
+    for my $paragraph (@$group_description) {
+      $group_description_string .= $paragraph."\n\n";
+    }
+    # remove the + sign after the last paragraph of the description
+    #if ($group_description_string) {
+    #  $group_description_string =~ s/\+$//;
+    #  chomp ($group_description_string);
+    #}
+    if ($group_description_string) {
+      $asciidocoutput .= $group_description_string;
+    }
+    # Add an example if there is one, like this:    include::../examples/example-logging-root-level.asciidoc[]
+    if ($group_example) {
+      $asciidocoutput .= "\n\n$group_example\n\n";
+    }
+
+    my $settings = $group->{settings};
+    for my $setting (@$settings) {
+
+      # Grab the setting name, description, and other properties
+      my $setting_name = $setting->{setting};
+      my $setting_id = $setting->{id};
+      my $setting_description = $setting->{description};   
+      my $setting_note = $setting->{note};
+      my $setting_warning = $setting->{warning};
+      my $setting_important = $setting->{important};
+      my $setting_tip = $setting->{tip};
+      my $setting_default = $setting->{default};
+      my $setting_type = $setting->{type};
+      my $setting_options = $setting->{options};
+      my $setting_platforms = $setting->{platforms};
+      my $setting_example = $setting->{example};
+      my $setting_state = $setting->{state};
+      my $deprecation_details = $setting->{deprecation_details};
+
+      # skip settings that are flagged as "hidden" 
+      if (($setting_state) && ($setting_state =~ /hidden/i)) {next;}
+
+      # Get the setting options and option descriptions and build the string
+      my $options = $setting->{options};
+      my $setting_options_string = "";
+      if ($options) {
+      for my $option (@$options) {
+        my $option_name = $option->{option};
+        # if ($option_name) {print "\nOPTION = ".$option_name;}
+        if ($option_name) {$setting_options_string .= '* `'.$option_name.'`';}
+        my $option_description = $option->{description};
+        # if ($option_description) {print "\nDESCRIPTION = ".$option_description;}
+        if ($option_description) {$setting_options_string .= ' - '.$option_description;}
+        $setting_options_string .= "\n";
+      }
+      }
+
+      # check if supported on Cloud (these settings are marked with a Cloud icon)
+      my $supported_cloud = 0;
+      for my $platform (@$setting_platforms) {
+        if ($platform =~ /cloud/) {$supported_cloud = 1;}
+      }
+
+      # build the description paragraphs
+      my $setting_description_string = "";
+      for my $paragraph (@$setting_description) {
+        $setting_description_string .= $paragraph."\n\n";
+      }
+
+      # Currently, we're just adding the "C" icon when Cloud is supported, but in future we might instead want to provide the supported platforms (cloud, serverless, self-managed) as a list.
+      #my $setting_platforms_string = "";
+      #for my $platform (@$setting_platforms) {
+      #  $setting_platforms_string .= '`'.$platform.'`, ';
+      #}
+      ## remove the comma after the last platform in the list
+      #if ($setting_platforms_string) {$setting_platforms_string =~ s/, $//;}
+
+      # Add the settings info to the asciidoc file contents
+      $asciidocoutput .= "\n";
+      if ($setting_id) {
+        $asciidocoutput .= "\n".'[['.$setting_id.']]'."\n";
+      }
+      $asciidocoutput .= '`'.$setting_name.'`';
+      if ($supported_cloud) {
+        $asciidocoutput .= ' {ess-icon}';
+      }
+      $asciidocoutput .= "::\n+\n====\n";
+
+      # Add a standard disclaimer for technical preview settings
+      if ($setting_state) {
+        if ($setting_state =~ /technical-preview/i) 
+          {
+            $asciidocoutput .= "\n\npreview::[]\n\n";
+          }
+
+        # Mark deprecated settings and add guidance (such as when it was deprecated) if there is any
+        elsif ($setting_state =~ /deprecated/i) 
+          {
+            $asciidocoutput .= "**Deprecated:** ";
+            if ($deprecation_details) {
+            $asciidocoutput .= $deprecation_details."\n\n";
+          }
+          }
+        # known setting_states are 'technical-preview', 'deprecated' and 'hidden'. Anything else is ignored.
+        else {
+          print "\nUnknown setting state: ".$setting_state."\n";
+        }
+      }
+
+      if ($setting_description_string) {
+        $asciidocoutput .= $setting_description_string;
+      }
+
+      if ($setting_note) {
+        $asciidocoutput .= "\nNOTE: ".$setting_note."\n";
+      }
+      if ($setting_warning) {
+        $asciidocoutput .= "\nWARNING: ".$setting_warning."\n";
+      }
+      if ($setting_important) {
+        $asciidocoutput .= "\nIMPORTANT: ".$setting_important."\n";
+      }
+      if ($setting_tip) {
+        $asciidocoutput .= "\nTIP: ".$setting_tip."\n";
+      }
+
+      # If any of these are defined (setting options, setting default value, settting type...) add those inside a box.
+      # We put a " +" at the end of each line to to achieve single spacing inside the box.
+
+      if (($setting_options_string) || ($setting_default) || ($setting_type)) {
+        if ($setting_options_string) {
+          $asciidocoutput .= "\nOptions:\n\n".$setting_options_string."\n";
+        }
+        if ($setting_default) {
+          $asciidocoutput .= "Default: ".'`'.$setting_default.'`'.' +'."\n";
+        }
+        # Removing this. Instead, settings supported on Cloud will be marked with the "C" icon.
+        # if ($setting_platforms_string) {
+        #   $asciidocoutput .= "+\nPlatforms: ".$setting_platforms_string."\n";
+        # }
+        if ($setting_type) {
+          $asciidocoutput .= 'Type: `'.$setting_type.'` +'."\n";
+        }
+      }
+
+      # Add an example if there is one, like this:    include::../examples/example-logging-root-level.asciidoc[]
+      if ($setting_example) {
+        $asciidocoutput .= "\n\n$setting_example\n\n";
+      }
+
+      $asciidocoutput .= "====\n";
+    }
+  }
+
+
+  # Just in case we need to grab all of the keys, this is how:
+  # foreach my $key (keys %hash) { ... }
+
+  $asciidocoutput .= "\n\n";
+
+  # write the contents into the generated asciidoc file
+  open (WRITE, "> $outputfile") or die("$!");
+  print WRITE $asciidocoutput;
+  close WRITE;
+  print "\nGenerated file: ".$outputfile;
+  ++$count;
+
+return;
+}
+

docs/settings-gen/readme.md

@@ -0,0 +1,97 @@
+# YAML-based settings documentation
+
+We're aiming to update the Kibana configuration settings pages to be based off of YAML-formatted source files. The approach has the advantages that:
+ - The YAML format makes it easier to add new settings and update existing ones. The setting data is separate from almost all formatting, whether Asciidoc or (future) Markdown.
+ - The HTML files will have a more consistent and user-friendly appearance.
+ - The YAML format makes it easier for teams to identify missing settings or settings that are lacking details that should be made available in the docs.
+
+The YAML settings files in the `settings-gen/source` folder are converted to Asciidoc source, located in the same directory, by means of the `parse-settings.pl` Perl script. Please do not update the generated Asciidoc files directly as your changes will be overwritten. Please make any required docs changes in the `<name>-settings.yml` files.
+
+Following is a schema for all available properties in a YAML settings file.
+
+
+
+## Schema with descriptions
+
+```
+product: <Required (string) - the Elastic product name, e.g. 'Elasticsearch', 'Kibana', 'Enterprise Search', 'Elasticsearch Service', 'Elastic Cloud Enterprise'>
+collection: <Required (string) - the settings page title, e.g. Alerting and action settings in Kibana>
+page_description:
+  - <"Optional (asciidoc) - A summary description that appears at the top of the settings page">
+
+groups:
+  - group: [Optional] (string) - Section title on the settings page, e.g. Preconfigured connector settings
+    id: [Optional] (string) - ID used for documentation links, e.g., general-alert-action-settings
+    description:
+     - [Optional] (asciidoc in quotes) - The description content that appears below the group title.
+     - [Optional] (asciidoc in quotes) - Paragraph 2
+     - [Optional] (asciidoc in quotes) - Paragraph 3
+    example: |
+      These lines are interpreted as literal strings.
+      Include any complex Asciidoc such as tables, lists, code examples, etc.
+      Note that comments marked by # are ignored
+
+    settings:
+      - setting: [Required] (string) - Setting name, e.g. xpack.encryptedSavedObjects.encryptionKey
+        setting_id: <Optional (string) - ID to used for documentation links, e.g., xpack-encryptedsavedobjects-encryptionkey.>
+        description:
+          - [Optional] (asciidoc in quotes) - The description content that appears below the group title.
+          - [Optional] (asciidoc in quotes) - Paragraph 2
+          - [Optional] (asciidoc in quotes) - Paragraph 3
+        state: [Optional] - 'deprecated', 'technical-preview', or 'hidden'
+        deprecation_details: [Optional] (asciidoc in quotes) - details about when it was deprecated and/or what setting to use instead
+        note: [Optional] (asciidoc in quotes) - Text to display in a 'note' callout
+        tip: [Optional] (asciidoc in quotes) - Text to display in a 'tip' callout
+        warning: [Optional] (asciidoc in quotes) - Text to display in a 'warning' callout
+        important: [Optional] (asciidoc in quotes) - Text to display in an 'important' callout
+        default: [Optional] (string) - The setting's default value
+        options:
+          - option: [Optional] (string) - A setting option, e.g., zh-cn
+            description: [Optional] (asciidoc in quotes) - Description of the setting option
+          - option: [Optional] (string) - A setting option, e.g., ja-jp
+            description: [Optional] (asciidoc in quotes) - Description of the setting option
+        type: [Optional] One of 'static' or 'dynamic'
+        platforms:
+          - [Optional] - one of cloud/serverless/self-managed
+          - [Optional] - one of cloud/serverless/self-managed
+          - [Optional] - one of cloud/serverless/self-managed
+        example: |
+          These lines are interpreted as literal strings.
+          Include any complex Asciidoc such as tables, lists, code examples, etc.
+          Note that comments marked by # are ignored
+```
+
+
+## Schema without descriptions (for easier cutting and pasting)
+
+```
+product: REQUIRED
+collection: REQUIRED
+
+groups:
+  - group: REQUIRED
+    id: REQUIRED
+    # description:
+    #  - ""
+    # example: example-group-name.asciidoc
+    settings:
+
+      - setting: REQUIRED
+        # id: 
+        description:
+          - "REQUIRED"
+        # state: deprecated/hidden/tech-preview
+        # deprecation_details: ""
+        # note: ""
+        # tip: ""
+        # warning: ""
+        # important: ""
+        # default:
+        # options:
+        #   - option:
+        #     description: ""
+        # type: static/dynamic
+        # platforms:
+        #   - cloud/serverless/self-managed
+        # example: |
+```