[ Jekyll ] [ SpecInsert ] omit_header (#8766)

* Spec Insert
A program that insert API Components generated from the OpenSearch OpenAPI Spec into markdown files

Signed-off-by: Theo Truong <[email protected]>

* # vale:reviewdog

Signed-off-by: Theo Truong <[email protected]>

* # Correction on cron job run time.

Signed-off-by: Theo Truong <[email protected]>

* Apply suggestions from code review

Co-authored-by: Naarcha-AWS <[email protected]>
Co-authored-by: Daniel (dB.) Doubrovkine <[email protected]>
Signed-off-by: Theo N. Truong <[email protected]>

* Added `omit_header` argument for Spec Insert components
(Some minor refactoring to DRY the code as well)

Signed-off-by: Theo Truong <[email protected]>

* Apply suggestions from code review

Signed-off-by: Naarcha-AWS <[email protected]>

---------

Signed-off-by: Theo Truong <[email protected]>
Signed-off-by: Theo N. Truong <[email protected]>
Signed-off-by: Naarcha-AWS <[email protected]>
Co-authored-by: Naarcha-AWS <[email protected]>
Co-authored-by: Daniel (dB.) Doubrovkine <[email protected]>

DEVELOPER_GUIDE.md

@@ -1,12 +1,13 @@
 # Developer guide
- - [Introduction](#introduction)
- - [Starting the Jekyll server locally](#starting-the-jekyll-server-locally)
- - [Using the spec-insert Jekyll plugin](#using-the-spec-insert-jekyll-plugin)
-   - [Inserting query parameters](#inserting-query-parameters)
-   - [Inserting path parameters](#inserting-path-parameters)
-   - [Inserting paths and HTTP methods](#inserting-paths-and-http-methods)
-   - [Ignoring files and folders](#ignoring-files-and-folders)
-   - [CI/CD](#cicd)
+- [Introduction](#introduction)
+- [Starting the Jekyll server locally](#starting-the-jekyll-server-locally)
+- [Using the spec-insert Jekyll plugin](#using-the-spec-insert-jekyll-plugin)
+  - [Ignoring files and folders](#ignoring-files-and-folders)
+- [CI/CD](#cicd)
+- [Spec insert components](#spec-insert-components)
+  - [Query parameters](#query-parameters)
+  - [Path parameters](#path-parameters)
+  - [Paths and HTTP methods](#paths-and-http-methods)
 
 ## Introduction
 
@@ -31,7 +32,7 @@ Edit your Markdown file and insert the following snippet where you want render a
 <!-- spec_insert_start 
 api: <API_NAME>
 component: <COMPONENT_NAME>
-other_param: <OTHER_PARAM>
+other_argument: <OTHER_ARGUMENT>
 -->
 
 This is where the API component will be inserted.
@@ -59,10 +60,20 @@ The plugin will pull the newest OpenSearch API spec from its [repository](https:
 bundle exec jekyll spec-insert --refresh-spec
 ```
 
-### Inserting query parameters
+### Ignoring files and folders
+The `spec-insert` plugin ignores all files and folders listed in the [./_config.yml#exclude](./_config.yml) list, which is also the list of files and folders that Jekyll ignores.
 
-To insert the API query parameters table, use the following snippet:
+## CI/CD
+The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the API components are up to date in the documentation. This is performed through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Actions workflow, which creates a pull request containing the updated API components every Sunday.
 
+## Spec insert components
+All spec insert components accept the following arguments:
+- `api` (String; required): The name of the API to render the component from. This is equivalent to the `x-operation-group` field in the OpenSearch OpenAPI Spec.
+- `component` (String; required): The name of the component to render,  such as `query_parameters`, `path_parameters`, or `paths_and_http_methods`.
+- `omit_header` (Boolean; Default is `false`): If set to `true`, the markdown header of the component will not be rendered.
+
+### Query parameters
+To insert the API query parameters table of the `cat.indices` API, use the following snippet:
 ```markdown
 <!-- spec_insert_start
 api: cat.indices
@@ -71,18 +82,18 @@ component: query_parameters
 <!-- spec_insert_end -->
 ```
 
-This will insert the query parameters of the `cat.indices` API into the `.md` file with three default columns: `Parameter`, `Type`, and `Description`. There are five columns that can be inserted: `Parameter`, `Type`, `Description`, `Required`, and `Default`. When `Required`/`Default` is not chosen, the information will be written in the `Description` column.
-
-You can customize the query parameters table with the following columns:
+This will insert the query parameters of the `cat.indices` API into the `.md` file with three default columns: `Parameter`, `Type`, and `Description`. You can customize the query parameters table by adding the `columns` argument which accepts a comma-separated list of column names. The available column names are:
 
 - `Parameter`
 - `Type`
 - `Description`
-- `Required` 
+- `Required`
 - `Default`
 
- You can also customize this component with the following settings:
-
+_When `Required`/`Default` is not chosen, the information will be written in the `Description` column._
+
+You can also customize this component with the following settings:
+
 - `include_global` (Boolean; default is `false`): Includes global query parameters in the table.
 - `include_deprecated` (Boolean; default is `true`): Includes deprecated parameters in the table.
 - `pretty` (Boolean; default is `false`): Renders the table in the pretty format instead of the compact format.
@@ -100,36 +111,23 @@ pretty: true
 <!-- spec_insert_end -->
 ```
 
-### Inserting path parameters
-
-To insert the `indices.create` API path parameters table, use the following snippet:
-
+### Path parameters
+To insert path parameters table of the `indices.create` API, use the following snippet:
 ```markdown
 <!-- spec_insert_start
 api: indices.create
 component: path_parameters
 -->
 <!-- spec_insert_end -->
 ```
+This table behaves the same as the query parameters table except that it does not accept the `include_global` argument.
 
-This table behaves identically to the query parameters table except that it does not accept the `include_global` argument.
-
-### Inserting paths and HTTP methods
-
+### Paths and HTTP methods
 To insert paths and HTTP methods for the `search` API, use the following snippet:
-
 ```markdown
 <!-- spec_insert_start
 api: search
 component: paths_and_http_methods
 -->
 <!-- spec_insert_end -->
-```
-
-### Ignoring files and folders
-
-The `spec-insert` plugin ignores all files and folders listed in the [./_config.yml#exclude](./_config.yml) list, which is also the list of files and folders that Jekyll ignores.
-
-### CI/CD
-
-The `spec-insert` plugin is run as part of the CI/CD pipeline to ensure that the API components are up to date in the documentation. This is performed through the [update-api-components.yml](.github/workflows/update-api-components.yml) GitHub Actions workflow, which creates a pull request containing the updated API components every Sunday.
+```

spec-insert/lib/insert_arguments.rb

@@ -48,6 +48,11 @@ def include_deprecated
     parse_boolean(@raw['include_deprecated'], default: true)
   end
 
+  # @return [Boolean]
+  def omit_header
+    parse_boolean(@raw['omit_header'], default: false)
+  end
+
   private
 
   # @param [String] value comma-separated array

spec-insert/lib/renderers/base_mustache_renderer.rb

@@ -6,13 +6,15 @@
 class BaseMustacheRenderer < Mustache
   self.template_path = "#{__dir__}/templates"
 
-  def initialize(output_file = nil)
-    @output_file = output_file
-    super
+  # @param [Action] action API Action
+  # @param [InsertArguments] args
+  def initialize(action, args)
+    super()
+    @action = action
+    @args = args
   end
 
-  def generate
-    raise 'Output file not specified' unless @output_file
-    @output_file&.write(render)
+  def omit_header
+    @args.omit_header
   end
 end

spec-insert/lib/renderers/parameter_table_renderer.rb

@@ -11,7 +11,6 @@ def initialize(parameters, args)
     @pretty = args.pretty
     @parameters = parameters
     @parameters = @parameters.reject(&:deprecated) unless args.include_deprecated
-    @parameters += Parameter.global if args.include_global
     @parameters = @parameters.sort_by { |arg| [arg.required ? 0 : 1, arg.deprecated ? 1 : 0, arg.name] }
   end
 

spec-insert/lib/renderers/path_parameters.rb

@@ -7,15 +7,8 @@
 class PathParameters < BaseMustacheRenderer
   self.template_file = "#{__dir__}/templates/path_parameters.mustache"
 
-  # @param [Action] action API Action
-  # @param [InsertArguments] args
-  def initialize(action, args)
-    super(nil)
-    @params = action.arguments.select { |arg| arg.location == ArgLocation::PATH }
-    @args = args
-  end
-
   def table
-    ParameterTableRenderer.new(@params, @args).render
+    params = @action.arguments.select { |arg| arg.location == ArgLocation::PATH }
+    ParameterTableRenderer.new(params, @args).render
   end
 end

spec-insert/lib/renderers/paths_and_methods.rb

@@ -6,12 +6,6 @@
 class PathsAndMethods < BaseMustacheRenderer
   self.template_file = "#{__dir__}/templates/paths_and_methods.mustache"
 
-  # @param [Action] action API Action
-  def initialize(action)
-    super
-    @action = action
-  end
-
   def operations
     ljust = @action.operations.map { |op| op.http_verb.length }.max
     @action.operations

spec-insert/lib/renderers/query_parameters.rb

@@ -7,19 +7,9 @@
 class QueryParameters < BaseMustacheRenderer
   self.template_file = "#{__dir__}/templates/query_parameters.mustache"
 
-  # @param [Action] action API Action
-  # @param [InsertArguments] args
-  def initialize(action, args)
-    super(nil)
-    @params = action.arguments.select { |arg| arg.location == ArgLocation::QUERY }
-    @args = args
-  end
-
   def table
-    ParameterTableRenderer.new(@params, @args).render
-  end
-
-  def optional
-    @params.none?(&:required)
+    params = @action.arguments.select { |arg| arg.location == ArgLocation::QUERY }
+    params += Parameter.global if @args.include_global
+    ParameterTableRenderer.new(params, @args).render
   end
 end

spec-insert/lib/renderers/spec_insert.rb

@@ -15,9 +15,9 @@ class SpecInsert < BaseMustacheRenderer
 
   # @param [Array<String>] arg_lines the lines between "<!-- doc_insert_start" and "-->"
   def initialize(arg_lines)
-    super
-    @args = InsertArguments.new(arg_lines)
-    @action = Action.actions[@args.api]
+    args = InsertArguments.new(arg_lines)
+    action = Action.actions[args.api]
+    super(action, args)
     raise SpecInsertError, '`api` argument not specified.' unless @args.api
     raise SpecInsertError, "API Action '#{@args.api}' does not exist in the spec." unless @action
   end
@@ -34,7 +34,7 @@ def content
     when :path_parameters
       PathParameters.new(@action, @args).render
     when :paths_and_http_methods
-      PathsAndMethods.new(@action).render
+      PathsAndMethods.new(@action, @args).render
     else
       raise SpecInsertError, "Invalid component: #{@args.component}"
     end

spec-insert/lib/renderers/templates/path_parameters.mustache

@@ -1,2 +1,4 @@
+{{^omit_header}}
 ## Path parameters
+{{/omit_header}}
 {{{table}}}

spec-insert/lib/renderers/templates/paths_and_methods.mustache

@@ -1,4 +1,6 @@
+{{^omit_header}}
 ## Paths and HTTP methods
+{{/omit_header}}
 ```json
 {{#operations}}
 {{{verb}}} {{{path}}}

spec-insert/lib/renderers/templates/query_parameters.mustache

@@ -1,5 +1,7 @@
+{{^omit_header}}
 ## Query parameters
 {{#optional}}
 All query parameters are optional.
 {{/optional}}
+{{/omit_header}}
 {{{table}}}

spec-insert/spec/_fixtures/expected_output/param_tables.md

@@ -34,8 +34,8 @@ Query Parameters Example with only Parameter and Description Columns
 api: search
 component: query_parameters
 columns: Parameter, Description
+omit_header: true
 -->
-## Query parameters
 Parameter | Description
 :--- | :---
 `analyze_wildcard` | **(Required)** If true, wildcard and prefix queries are analyzed. This parameter can only be used when the q query string parameter is specified.

spec-insert/spec/_fixtures/input/param_tables.md

@@ -29,6 +29,7 @@ Query Parameters Example with only Parameter and Description Columns
 api: search
 component: query_parameters
 columns: Parameter, Description
+omit_header: true
 -->
 THIS
 TEXT