From 7106fb3da7ca4c559c6313522fca3333582dbaba Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Fri, 24 Jan 2025 16:16:20 -0700 Subject: [PATCH 1/3] [Spec-Insert] Removed default short-circuit. Replaced with -F flag. Signed-off-by: Theo Truong --- .github/workflows/update-api-components.yml | 2 +- DEVELOPER_GUIDE.md | 8 +++++++- spec-insert/config.yml | 4 +++- spec-insert/lib/jekyll-spec-insert.rb | 20 +++++++++++++------ .../lib/renderers/parameter_table_renderer.rb | 2 +- spec-insert/spec/mock_config.yml | 2 ++ 6 files changed, 28 insertions(+), 10 deletions(-) diff --git a/.github/workflows/update-api-components.yml b/.github/workflows/update-api-components.yml index 42cc1d2827..c4377267a4 100644 --- a/.github/workflows/update-api-components.yml +++ b/.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 diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 13b172273a..e7b223b85d 100644 --- a/DEVELOPER_GUIDE.md +++ b/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, it simply prints out the error then 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. diff --git a/spec-insert/config.yml b/spec-insert/config.yml index 78c982c77c..a160642965 100644 --- a/spec-insert/config.yml +++ b/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}}" \ No newline at end of file + with: "{{site.url}}{{site.baseurl}}" + - replace: "\n" + with: " " \ No newline at end of file diff --git a/spec-insert/lib/jekyll-spec-insert.rb b/spec-insert/lib/jekyll-spec-insert.rb index 14a8997cc8..8dc51f3aef 100644 --- a/spec-insert/lib/jekyll-spec-insert.rb +++ b/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,26 @@ 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 + Jekyll.logger.error "Error processing #{file}: #{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 } diff --git a/spec-insert/lib/renderers/parameter_table_renderer.rb b/spec-insert/lib/renderers/parameter_table_renderer.rb index 2ab439be5c..e07e820c29 100644 --- a/spec-insert/lib/renderers/parameter_table_renderer.rb +++ b/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}`)_" diff --git a/spec-insert/spec/mock_config.yml b/spec-insert/spec/mock_config.yml index 9b7b5c9c59..15e31f24ea 100644 --- a/spec-insert/spec/mock_config.yml +++ b/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 \ No newline at end of file From 9991730f08e80ff394aa96bb0a59147d9cebae2d Mon Sep 17 00:00:00 2001 From: Theo Truong Date: Fri, 24 Jan 2025 16:28:31 -0700 Subject: [PATCH 2/3] # Always catch SpecInsertError Signed-off-by: Theo Truong --- spec-insert/lib/doc_processor.rb | 6 ++---- spec-insert/lib/jekyll-spec-insert.rb | 3 ++- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/spec-insert/lib/doc_processor.rb b/spec-insert/lib/doc_processor.rb index 0aaa01061a..3cddb5939c 100644 --- a/spec-insert/lib/doc_processor.rb +++ b/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 diff --git a/spec-insert/lib/jekyll-spec-insert.rb b/spec-insert/lib/jekyll-spec-insert.rb index 8dc51f3aef..6c4c1fb078 100644 --- a/spec-insert/lib/jekyll-spec-insert.rb +++ b/spec-insert/lib/jekyll-spec-insert.rb @@ -39,7 +39,8 @@ 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 - Jekyll.logger.error "Error processing #{file}: #{e.message}" + 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) From e1544ab5979f2f7be309c6dfc6f6e4f1021418bf Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 24 Jan 2025 17:37:57 -0600 Subject: [PATCH 3/3] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- DEVELOPER_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index e7b223b85d..d81038ef5b 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -52,7 +52,7 @@ If you are working on multiple Markdown files and do not want to keep running th bundle exec jekyll spec-insert -W ``` -By default, when the plugin encounters an error, when processing a file, it simply prints out the error then 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: +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