[Spec-Insert] Removed default short-circuit. Replaced with -F flag.

.github/workflows/update-api-components.yml

@@ -24,7 +24,7 @@ jobs:
       - run: bundle install
 
       - name: Download spec and insert into documentation
-        run: bundle exec jekyll spec-insert
+        run: bundle exec jekyll spec-insert -F -R
 
       - name: Get current date
         id: date

DEVELOPER_GUIDE.md

@@ -49,7 +49,13 @@ bundle exec jekyll spec-insert
 If you are working on multiple Markdown files and do not want to keep running the `jekyll spec-insert` command, you can add the `--watch` (or `-W`) flag to the command to watch for changes in the Markdown files and automatically render the API components:
 
 ```shell
-bundle exec jekyll spec-insert --watch
+bundle exec jekyll spec-insert -W
+```
+
+By default, when the plugin encounters an error when processing a file, the plugin prints out the error than moves on to the next file. If you want it to short-circuit when an error occurs, add the `--fail-on-error` (or `-F`) flag to the command:
+
+```shell
+bundle exec jekyll spec-insert -F
 ```
 
 Depending on the text editor you are using, you may need to manually reload the file from disk to see the changes applied by the plugin if the editor does not automatically reload the file periodically.

spec-insert/config.yml

@@ -8,4 +8,6 @@ param_table:
 # Replace text in every description in the spec file
 text_replacements:
   - replace: "https://opensearch.org/docs/latest"
-    with: "{{site.url}}{{site.baseurl}}"
+    with: "{{site.url}}{{site.baseurl}}"
+  - replace: "\n"
+    with: " "

spec-insert/lib/doc_processor.rb

@@ -17,7 +17,6 @@ def initialize(file_path, logger:)
   # Processes the file, replacing spec-insert blocks with rendered content
   # @param [Boolean] write_to_file Whether to write the changes back to the file
   def process(write_to_file: true)
-    relative_path = @file_path.relative_path_from(Pathname.new(Dir.pwd))
     lines = File.readlines(@file_path)
     original_content = lines.join
     insertions = find_insertions(lines)
@@ -27,11 +26,10 @@ def process(write_to_file: true)
     rendered_content = lines.join
     if write_to_file && rendered_content != original_content
       File.write(@file_path, rendered_content)
-      @logger.info "Spec components inserted into #{relative_path} successfully."
+      relative_path = @file_path.relative_path_from(Pathname.new(Dir.pwd))
+      @logger.info "Successfully updated #{relative_path}."
     end
     rendered_content
-  rescue SpecInsertError => e
-    @logger.error "Error processing #{relative_path}. #{e.message}"
   end
 
   private

spec-insert/lib/jekyll-spec-insert.rb

@@ -14,13 +14,14 @@ def self.init_with_program(prog)
       c.syntax 'spec-insert [options]'
       c.option 'watch', '--watch', '-W', 'Watch for changes and rebuild'
       c.option 'refresh-spec', '--refresh-spec', '-R', 'Redownload the OpenSearch API specification'
+      c.option 'fail-on-error', '--fail-on-error', '-F', 'Fail on error'
       c.action do |_args, options|
         spec_file = File.join(Dir.pwd, 'spec-insert/opensearch-openapi.yaml')
         excluded_paths = YAML.load_file('_config.yml')['exclude']
         download_spec(spec_file, forced: options['refresh-spec'])
         SpecHash.load_file(spec_file)
-        run_once(excluded_paths)
-        watch(excluded_paths) if options['watch']
+        run_once(excluded_paths, fail_on_error: options['fail-on-error'])
+        watch(excluded_paths, fail_on_error: options['fail-on-error']) if options['watch']
       end
     end
   end
@@ -34,19 +35,27 @@ def self.download_spec(spec_file, forced: false)
            "-o #{spec_file}"
   end
 
-  def self.run_once(excluded_paths)
+  def self.process_file(file, fail_on_error: false)
+    DocProcessor.new(file, logger: Jekyll.logger).process
+  rescue StandardError => e
+    raise e if fail_on_error
+    relative_path = Pathname(file).relative_path_from(Pathname.new(Dir.pwd))
+    Jekyll.logger.error "Error processing #{relative_path}: #{e.message}"
+  end
+
+  def self.run_once(excluded_paths, fail_on_error: false)
     excluded_paths = excluded_paths.map { |path| File.join(Dir.pwd, path) }
     Dir.glob(File.join(Dir.pwd, '**/*.md'))
        .filter { |file| excluded_paths.none? { |excluded| file.start_with?(excluded) } }
-       .each { |file| DocProcessor.new(file, logger: Jekyll.logger).process }
+       .each { |file| process_file(file, fail_on_error: fail_on_error) }
   end
 
-  def self.watch(excluded_paths)
+  def self.watch(excluded_paths, fail_on_error: false)
     Jekyll.logger.info "\nWatching for changes...\n"
     excluded_paths = excluded_paths.map { |path| /\.#{path}$/ }
 
     Listen.to(Dir.pwd, only: /\.md$/, ignore: excluded_paths) do |modified, added, _removed|
-      (modified + added).each { |file| DocProcessor.new(file, logger: Jekyll.logger).process }
+      (modified + added).each { |file| process_file(file, fail_on_error: fail_on_error) }
     end.start
 
     trap('INT') { exit }

spec-insert/lib/renderers/parameter_table_renderer.rb

@@ -60,7 +60,7 @@ def row(param)
   def description(param)
     deprecation = deprecation(param)
     required = param.required && @columns.exclude?('Required') ? '**(Required)** ' : ''
-    description = param.description.gsub("\n", ' ')
+    description = param.description
     valid_values = valid_values(param)
     default = param.default.nil? || @columns.include?('Default') ? '' : " _(Default: `#{param.default}`)_"
 

spec-insert/spec/mock_config.yml

@@ -8,5 +8,7 @@ param_table:
 text_replacements:
   - replace: "https://opensearch.org/docs/latest"
     with: "{{site.url}}{{site.baseurl}}"
+  - replace: "\n"
+    with: " "
   - replace: master node
     with: cluster manager node