From 1d2b7506b6666fe1963def2b1d8f59839a1f6603 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 17:09:58 -0500 Subject: [PATCH 01/12] Add Github link support to beta and experimental macros We add the `experimental::[]` and `beta::[]` macros to document features that are not yet ready for GA. However, these tags don't currently indicate what steps are needed to get a feature to GA. With these changes, users can include a GitHub issue for the feature in the `experimental::[]` or `beta::[]`. When provided, a concise sentence and link is generated for the issue. --- README.asciidoc | 25 +++++++++++++++++-- .../lib/care_admonition/extension.rb | 23 +++++++++++++++-- 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index a6341c31696e5..5769c2d0376d4 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1479,7 +1479,13 @@ Text about old functionality... == Experimental and Beta APIs or parameters that are experimental or in beta can be marked as such, using -markup similar to that used in <>. For instance: +markup similar to that used in <>. + +In the block format, you have the option of adding a related GitHub issue. If +both custom text and a GitHub issue are provided, the GitHub issue **must** be +provided second. + +For instance: [source,asciidoc] ---------------------------------- @@ -1488,8 +1494,12 @@ markup similar to that used in <>. For instance: experimental::[] +experimental::[https://github.com/elastic/docs/issues/505] + experimental::[Custom text goes here] +experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505] + Text about new feature... [[old-feature]] @@ -1510,10 +1520,13 @@ a new experimental parameter: experimental::[] +experimental::[https://github.com/elastic/docs/issues/505] + experimental::[Custom text goes here] -Text about new feature... +experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505] +Text about new feature... [[old-feature]] === Established feature @@ -1532,8 +1545,12 @@ a new experimental parameter: beta::[] +beta::[https://github.com/elastic/docs/issues/505] + beta::[Custom text goes here] +beta::[Custom text goes here,https://github.com/elastic/docs/issues/505] + Text about new feature... [[old-beta-feature]] @@ -1554,8 +1571,12 @@ a new beta parameter: beta::[] +beta::[https://github.com/elastic/docs/issues/505] + beta::[Custom text goes here] +beta::[Custom text goes here,https://github.com/elastic/docs/issues/505] + Text about new feature... [[old-beta-feature]] diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index f397496ef2a24..c4a7d17e43738 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -34,7 +34,7 @@ def activate(registry) # Block care admonition. class ChangeAdmonitionBlock < Asciidoctor::Extensions::BlockMacroProcessor use_dsl - name_positional_attributes :passtext + name_positional_attributes :passtext, :github def initialize(role, default_text) super(nil) @@ -43,9 +43,28 @@ def initialize(role, default_text) end def process(parent, _target, attrs) + + text = attrs[:passtext] + link_pattern = /^https?:\/\/github\.com\/elastic\/\S+[^\/]\/issues\/\d+$/ + + ## If the passtext looks like a Github link, use it. + if text && text.match(link_pattern) + github_link = attrs[:passtext] + text = @default_text + else + github_link = attrs[:github] + text ||= @default_text + end + + if github_link + github_issue = github_link.split('/').last + github_text = "For feature status, see #{github_link}[\##{github_issue}]." + text += " " + github_text + end + Asciidoctor::Block.new( parent, :admonition, - source: attrs[:passtext] || @default_text, + source: text, attributes: { 'role' => @role, 'name' => 'warning', From cc3fe0c009eed6500a5f7169411ae6ecca353438 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 18:26:03 -0500 Subject: [PATCH 02/12] Fix ruby style for tests --- resources/asciidoctor/lib/care_admonition/extension.rb | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index c4a7d17e43738..474b9ea41a6a3 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -43,12 +43,11 @@ def initialize(role, default_text) end def process(parent, _target, attrs) - text = attrs[:passtext] link_pattern = /^https?:\/\/github\.com\/elastic\/\S+[^\/]\/issues\/\d+$/ ## If the passtext looks like a Github link, use it. - if text && text.match(link_pattern) + if text&.match(link_pattern) github_link = attrs[:passtext] text = @default_text else @@ -58,8 +57,10 @@ def process(parent, _target, attrs) if github_link github_issue = github_link.split('/').last - github_text = "For feature status, see #{github_link}[\##{github_issue}]." - text += " " + github_text + github_text = <<~TEXT + For feature status,see #{github_link}[\##{github_issue}]. + TEXT + text += ' ' + github_text end Asciidoctor::Block.new( From b7ba3f7954891d77f5085613759970dc786e40f6 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 18:29:44 -0500 Subject: [PATCH 03/12] Re-add space --- resources/asciidoctor/lib/care_admonition/extension.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 474b9ea41a6a3..0848833ceae0f 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -58,7 +58,7 @@ def process(parent, _target, attrs) if github_link github_issue = github_link.split('/').last github_text = <<~TEXT - For feature status,see #{github_link}[\##{github_issue}]. + For feature status, see #{github_link}[\##{github_issue}]. TEXT text += ' ' + github_text end From 1dbca3690e1f50b11193e93c8f74064633055dad Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 18:39:38 -0500 Subject: [PATCH 04/12] More style fixes --- resources/asciidoctor/lib/care_admonition/extension.rb | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 0848833ceae0f..9d45ab1f76be5 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -44,17 +44,14 @@ def initialize(role, default_text) def process(parent, _target, attrs) text = attrs[:passtext] - link_pattern = /^https?:\/\/github\.com\/elastic\/\S+[^\/]\/issues\/\d+$/ - - ## If the passtext looks like a Github link, use it. - if text&.match(link_pattern) + gh_pattern = %r{^https?:\/\/github\.com\/elastic\/\S+[^\/]\/issues\/\d+$} + if text&.match(gh_pattern) github_link = attrs[:passtext] text = @default_text else github_link = attrs[:github] text ||= @default_text end - if github_link github_issue = github_link.split('/').last github_text = <<~TEXT @@ -62,7 +59,6 @@ def process(parent, _target, attrs) TEXT text += ' ' + github_text end - Asciidoctor::Block.new( parent, :admonition, source: text, From c57cd505769924737556329cdbb9c0cb2b2571be Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 19:03:17 -0500 Subject: [PATCH 05/12] Reorg for rubocop tests --- .../lib/care_admonition/extension.rb | 24 +++++++++++-------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 9d45ab1f76be5..79fdf60a854c7 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -42,10 +42,20 @@ def initialize(role, default_text) @default_text = default_text end + def + + def generate_github_text(github_link,text) + github_issue = github_link.split('/').last.chomp!('/') + github_text = <<~TEXT + For feature status, see #{github_link}[\##{github_issue}]. + TEXT + text += ' ' + github_text + return text + end + def process(parent, _target, attrs) text = attrs[:passtext] - gh_pattern = %r{^https?:\/\/github\.com\/elastic\/\S+[^\/]\/issues\/\d+$} - if text&.match(gh_pattern) + if text.start_with("http") github_link = attrs[:passtext] text = @default_text else @@ -53,16 +63,10 @@ def process(parent, _target, attrs) text ||= @default_text end if github_link - github_issue = github_link.split('/').last - github_text = <<~TEXT - For feature status, see #{github_link}[\##{github_issue}]. - TEXT - text += ' ' + github_text + text = generate_github_text(github_link,text) end Asciidoctor::Block.new( - parent, :admonition, - source: text, - attributes: { + parent, :admonition, source: text, attributes: { 'role' => @role, 'name' => 'warning', 'style' => 'warning', From c122a7cbd9f2d1469f21c2f34e81e4b63e372526 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 19:10:32 -0500 Subject: [PATCH 06/12] Fix breaks --- resources/asciidoctor/lib/care_admonition/extension.rb | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 79fdf60a854c7..bb816594809e3 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -42,10 +42,8 @@ def initialize(role, default_text) @default_text = default_text end - def - def generate_github_text(github_link,text) - github_issue = github_link.split('/').last.chomp!('/') + github_issue = github_link.split('/').last.chomp('/') github_text = <<~TEXT For feature status, see #{github_link}[\##{github_issue}]. TEXT @@ -55,7 +53,7 @@ def generate_github_text(github_link,text) def process(parent, _target, attrs) text = attrs[:passtext] - if text.start_with("http") + if text&.start_with?("http") github_link = attrs[:passtext] text = @default_text else From 816735eba50fc003382158826ae921c58f561435 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 19:13:19 -0500 Subject: [PATCH 07/12] Address review feedback --- resources/asciidoctor/lib/care_admonition/extension.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index bb816594809e3..e76e2964e2c55 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -34,7 +34,7 @@ def activate(registry) # Block care admonition. class ChangeAdmonitionBlock < Asciidoctor::Extensions::BlockMacroProcessor use_dsl - name_positional_attributes :passtext, :github + name_positional_attributes :passtext, :issue_url def initialize(role, default_text) super(nil) @@ -57,7 +57,7 @@ def process(parent, _target, attrs) github_link = attrs[:passtext] text = @default_text else - github_link = attrs[:github] + github_link = attrs[:issue_url] text ||= @default_text end if github_link From ab4881dd48734c53a7ddd3f80a354990e47a5d72 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 19:48:01 -0500 Subject: [PATCH 08/12] More reorg. Rubocop is harsh. --- .../lib/care_admonition/extension.rb | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index e76e2964e2c55..97a0fb7d8e143 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -42,27 +42,28 @@ def initialize(role, default_text) @default_text = default_text end - def generate_github_text(github_link,text) - github_issue = github_link.split('/').last.chomp('/') - github_text = <<~TEXT - For feature status, see #{github_link}[\##{github_issue}]. + def generate_issue_text(text, issue_url) + issue_no = issue_url.split('/').last.chomp('/') + issue_text = <<~TEXT + For feature status, see #{issue_url}[\##{issue_no}]. TEXT - text += ' ' + github_text - return text + text += ' ' + issue_text end - def process(parent, _target, attrs) - text = attrs[:passtext] - if text&.start_with?("http") - github_link = attrs[:passtext] + def generate_text(text, issue_url) + if text&.start_with?('http') + issue_url = text text = @default_text else - github_link = attrs[:issue_url] + issue_url = issue_url text ||= @default_text end - if github_link - text = generate_github_text(github_link,text) - end + text = generate_issue_text(text,issue_url) if issue_url + text + end + + def process(parent, _target, attrs) + text = generate_text(attrs[:passtext], attrs[:issue_url]) Asciidoctor::Block.new( parent, :admonition, source: text, attributes: { 'role' => @role, From d58fb6bdb90c3136d774e90c1afc773fbc7c9640 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 19:54:30 -0500 Subject: [PATCH 09/12] iter --- resources/asciidoctor/lib/care_admonition/extension.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 97a0fb7d8e143..01622d9866042 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -47,7 +47,7 @@ def generate_issue_text(text, issue_url) issue_text = <<~TEXT For feature status, see #{issue_url}[\##{issue_no}]. TEXT - text += ' ' + issue_text + text + ' ' + issue_text end def generate_text(text, issue_url) @@ -58,7 +58,7 @@ def generate_text(text, issue_url) issue_url = issue_url text ||= @default_text end - text = generate_issue_text(text,issue_url) if issue_url + text = generate_issue_text(text, issue_url) if issue_url text end From ab7ed494878ecee925d58a543c4ff90f614d0a92 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 21 Jan 2020 20:15:01 -0500 Subject: [PATCH 10/12] Add unit tests. Add support for {issue}. --- .../lib/care_admonition/extension.rb | 30 +++++++---- .../asciidoctor/spec/care_admonition_spec.rb | 50 +++++++++++++++++++ 2 files changed, 70 insertions(+), 10 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index 01622d9866042..dbbd0325b4c96 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -42,26 +42,36 @@ def initialize(role, default_text) @default_text = default_text end - def generate_issue_text(text, issue_url) - issue_no = issue_url.split('/').last.chomp('/') - issue_text = <<~TEXT - For feature status, see #{issue_url}[\##{issue_no}]. - TEXT - text + ' ' + issue_text - end - def generate_text(text, issue_url) - if text&.start_with?('http') + if text&.start_with?('http', '{issue}') issue_url = text text = @default_text else issue_url = issue_url text ||= @default_text end - text = generate_issue_text(text, issue_url) if issue_url + text = add_issue_text(text, issue_url) if issue_url text end + def add_issue_text(text, issue_url) + issue_num = get_issue_num(issue_url) + issue_text = <<~TEXT + For feature status, see #{issue_url}[\##{issue_num}]. + TEXT + text + ' ' + issue_text + end + + def get_issue_num(issue_url) + if issue_url.start_with?('http') + issue_num = issue_url.split('/').last + issue_num.chomp!('/') + else + issue_num = issue_url.sub('{issue}', '') + end + issue_num + end + def process(parent, _target, attrs) text = generate_text(attrs[:passtext], attrs[:issue_url]) Asciidoctor::Block.new( diff --git a/resources/asciidoctor/spec/care_admonition_spec.rb b/resources/asciidoctor/spec/care_admonition_spec.rb index 19b5ff950d062..fb41c1811abf5 100644 --- a/resources/asciidoctor/spec/care_admonition_spec.rb +++ b/resources/asciidoctor/spec/care_admonition_spec.rb @@ -71,6 +71,56 @@ def expect_block_admonition(body) expect(converted).to include "

#{key}[]

" end end + context 'when only a Github issue link is provided' do + let(:input) do + <<~ASCIIDOC + #{key}::[https://github.com/elastic/docs/issues/505] + ASCIIDOC + end + it 'has default text and github text' do + expect_block_admonition <<~HTML.strip +

#{default_text} For feature status, see #505.

+ HTML + end + end + context 'when only an {issue} link is provided' do + let(:input) do + <<~ASCIIDOC + :issue: https://github.com/elastic/docs/issues/ + #{key}::[{issue}505] + ASCIIDOC + end + it 'has default text and github text' do + expect_block_admonition <<~HTML.strip +

#{default_text} For feature status, see #505.

+ HTML + end + end + context 'when custom text and a Github issue link are provided' do + let(:input) do + <<~ASCIIDOC + #{key}::["Custom text." https://github.com/elastic/docs/issues/505] + ASCIIDOC + end + it 'has custom text and github text' do + expect_block_admonition <<~HTML.strip +

Custom text. For feature status, see #505.

+ HTML + end + end + context 'when custom text and an {issue} link are provided' do + let(:input) do + <<~ASCIIDOC + :issue: https://github.com/elastic/docs/issues/ + #{key}::["Custom text." {issue}505] + ASCIIDOC + end + it 'has custom text and github text' do + expect_block_admonition <<~HTML.strip +

Custom text. For feature status, see #505.

+ HTML + end + end end context 'inline form' do def expect_inline_admonition(text) From 19fa825a4fff892182888f25931b64b240ef2188 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 22 Jan 2020 09:26:49 -0500 Subject: [PATCH 11/12] Update README --- README.asciidoc | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 5769c2d0376d4..e9c95c6efbee1 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -1481,9 +1481,10 @@ Text about old functionality... APIs or parameters that are experimental or in beta can be marked as such, using markup similar to that used in <>. -In the block format, you have the option of adding a related GitHub issue. If -both custom text and a GitHub issue are provided, the GitHub issue **must** be -provided second. +In the block format, you have the option of adding a related GitHub issue link. +If both custom text and a GitHub link are provided, the GitHub link **must** be +provided second. If it's supported in your repo, you can use the `{issue}` +attribute in place of the GitHub issue link. For instance: @@ -1496,10 +1497,14 @@ experimental::[] experimental::[https://github.com/elastic/docs/issues/505] +experimental::[{issue}505] + experimental::[Custom text goes here] experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505] +experimental::[Custom text goes here,{issue}505] + Text about new feature... [[old-feature]] @@ -1522,10 +1527,14 @@ experimental::[] experimental::[https://github.com/elastic/docs/issues/505] +experimental::[{issue}505] + experimental::[Custom text goes here] experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505] +experimental::[Custom text goes here,{issue}505] + Text about new feature... [[old-feature]] === Established feature @@ -1547,10 +1556,14 @@ beta::[] beta::[https://github.com/elastic/docs/issues/505] +beta::[{issue}505] + beta::[Custom text goes here] beta::[Custom text goes here,https://github.com/elastic/docs/issues/505] +beta::[Custom text goes here,{issue}505] + Text about new feature... [[old-beta-feature]] @@ -1573,10 +1586,14 @@ beta::[] beta::[https://github.com/elastic/docs/issues/505] +beta::[{issue}505] + beta::[Custom text goes here] beta::[Custom text goes here,https://github.com/elastic/docs/issues/505] +beta::[Custom text goes here,{issue}505] + Text about new feature... [[old-beta-feature]] From bc8c4f7ee5a9a2ac0bd051f09cc9ac8cade5b3d3 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 23 Jan 2020 10:56:07 -0500 Subject: [PATCH 12/12] Address review feedback --- .../asciidoctor/lib/care_admonition/extension.rb | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/resources/asciidoctor/lib/care_admonition/extension.rb b/resources/asciidoctor/lib/care_admonition/extension.rb index dbbd0325b4c96..b26b56d4292d6 100644 --- a/resources/asciidoctor/lib/care_admonition/extension.rb +++ b/resources/asciidoctor/lib/care_admonition/extension.rb @@ -62,14 +62,10 @@ def add_issue_text(text, issue_url) text + ' ' + issue_text end - def get_issue_num(issue_url) - if issue_url.start_with?('http') - issue_num = issue_url.split('/').last - issue_num.chomp!('/') - else - issue_num = issue_url.sub('{issue}', '') - end - issue_num + def get_issue_num(url) + return url.split('/').last.chomp('/') if url.start_with?('http') + + url.sub('{issue}', '') end def process(parent, _target, attrs)