Skip to content

Commit a13cc8d

Browse files
jrodewigjrodewig
authored
Add Github link support to beta and experimental macros (#1705)
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.
1 parent dd6201e commit a13cc8d

File tree

3 files changed

+119
-6
lines changed

3 files changed

+119
-6
lines changed

‎README.asciidoc

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1479,7 +1479,14 @@ Text about old functionality...
14791479
== Experimental and Beta
14801480

14811481
APIs or parameters that are experimental or in beta can be marked as such, using
1482-
markup similar to that used in <<changes>>. For instance:
1482+
markup similar to that used in <<changes>>.
1483+
1484+
In the block format, you have the option of adding a related GitHub issue link.
1485+
If both custom text and a GitHub link are provided, the GitHub link **must** be
1486+
provided second. If it's supported in your repo, you can use the `{issue}`
1487+
attribute in place of the GitHub issue link.
1488+
1489+
For instance:
14831490

14841491
[source,asciidoc]
14851492
----------------------------------
@@ -1488,8 +1495,16 @@ markup similar to that used in <<changes>>. For instance:
14881495
14891496
experimental::[]
14901497
1498+
experimental::[https://github.com/elastic/docs/issues/505]
1499+
1500+
experimental::[{issue}505]
1501+
14911502
experimental::[Custom text goes here]
14921503
1504+
experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505]
1505+
1506+
experimental::[Custom text goes here,{issue}505]
1507+
14931508
Text about new feature...
14941509
14951510
[[old-feature]]
@@ -1510,10 +1525,17 @@ a new experimental parameter:
15101525

15111526
experimental::[]
15121527

1528+
experimental::[https://github.com/elastic/docs/issues/505]
1529+
1530+
experimental::[{issue}505]
1531+
15131532
experimental::[Custom text goes here]
15141533

1515-
Text about new feature...
1534+
experimental::[Custom text goes here,https://github.com/elastic/docs/issues/505]
15161535

1536+
experimental::[Custom text goes here,{issue}505]
1537+
1538+
Text about new feature...
15171539
[[old-feature]]
15181540
=== Established feature
15191541

@@ -1532,8 +1554,16 @@ a new experimental parameter:
15321554
15331555
beta::[]
15341556
1557+
beta::[https://github.com/elastic/docs/issues/505]
1558+
1559+
beta::[{issue}505]
1560+
15351561
beta::[Custom text goes here]
15361562
1563+
beta::[Custom text goes here,https://github.com/elastic/docs/issues/505]
1564+
1565+
beta::[Custom text goes here,{issue}505]
1566+
15371567
Text about new feature...
15381568
15391569
[[old-beta-feature]]
@@ -1554,8 +1584,16 @@ a new beta parameter:
15541584

15551585
beta::[]
15561586

1587+
beta::[https://github.com/elastic/docs/issues/505]
1588+
1589+
beta::[{issue}505]
1590+
15571591
beta::[Custom text goes here]
15581592

1593+
beta::[Custom text goes here,https://github.com/elastic/docs/issues/505]
1594+
1595+
beta::[Custom text goes here,{issue}505]
1596+
15591597
Text about new feature...
15601598

15611599
[[old-beta-feature]]

‎resources/asciidoctor/lib/care_admonition/extension.rb

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,19 +34,44 @@ def activate(registry)
3434
# Block care admonition.
3535
class ChangeAdmonitionBlock < Asciidoctor::Extensions::BlockMacroProcessor
3636
use_dsl
37-
name_positional_attributes :passtext
37+
name_positional_attributes :passtext, :issue_url
3838

3939
def initialize(role, default_text)
4040
super(nil)
4141
@role = role
4242
@default_text = default_text
4343
end
4444

45+
def generate_text(text, issue_url)
46+
if text&.start_with?('http', '{issue}')
47+
issue_url = text
48+
text = @default_text
49+
else
50+
issue_url = issue_url
51+
text ||= @default_text
52+
end
53+
text = add_issue_text(text, issue_url) if issue_url
54+
text
55+
end
56+
57+
def add_issue_text(text, issue_url)
58+
issue_num = get_issue_num(issue_url)
59+
issue_text = <<~TEXT
60+
For feature status, see #{issue_url}[\##{issue_num}].
61+
TEXT
62+
text + ' ' + issue_text
63+
end
64+
65+
def get_issue_num(url)
66+
return url.split('/').last.chomp('/') if url.start_with?('http')
67+
68+
url.sub('{issue}', '')
69+
end
70+
4571
def process(parent, _target, attrs)
72+
text = generate_text(attrs[:passtext], attrs[:issue_url])
4673
Asciidoctor::Block.new(
47-
parent, :admonition,
48-
source: attrs[:passtext] || @default_text,
49-
attributes: {
74+
parent, :admonition, source: text, attributes: {
5075
'role' => @role,
5176
'name' => 'warning',
5277
'style' => 'warning',

‎resources/asciidoctor/spec/care_admonition_spec.rb

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,56 @@ def expect_block_admonition(body)
7171
expect(converted).to include "<p>#{key}[]</p>"
7272
end
7373
end
74+
context 'when only a Github issue link is provided' do
75+
let(:input) do
76+
<<~ASCIIDOC
77+
#{key}::[https://github.com/elastic/docs/issues/505]
78+
ASCIIDOC
79+
end
80+
it 'has default text and github text' do
81+
expect_block_admonition <<~HTML.strip
82+
<p>#{default_text} For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
83+
HTML
84+
end
85+
end
86+
context 'when only an {issue} link is provided' do
87+
let(:input) do
88+
<<~ASCIIDOC
89+
:issue: https://github.com/elastic/docs/issues/
90+
#{key}::[{issue}505]
91+
ASCIIDOC
92+
end
93+
it 'has default text and github text' do
94+
expect_block_admonition <<~HTML.strip
95+
<p>#{default_text} For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
96+
HTML
97+
end
98+
end
99+
context 'when custom text and a Github issue link are provided' do
100+
let(:input) do
101+
<<~ASCIIDOC
102+
#{key}::["Custom text." https://github.com/elastic/docs/issues/505]
103+
ASCIIDOC
104+
end
105+
it 'has custom text and github text' do
106+
expect_block_admonition <<~HTML.strip
107+
<p>Custom text. For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
108+
HTML
109+
end
110+
end
111+
context 'when custom text and an {issue} link are provided' do
112+
let(:input) do
113+
<<~ASCIIDOC
114+
:issue: https://github.com/elastic/docs/issues/
115+
#{key}::["Custom text." {issue}505]
116+
ASCIIDOC
117+
end
118+
it 'has custom text and github text' do
119+
expect_block_admonition <<~HTML.strip
120+
<p>Custom text. For feature status, see <a href="https://github.com/elastic/docs/issues/505" class="ulink" target="_top">#505</a>.</p>
121+
HTML
122+
end
123+
end
74124
end
75125
context 'inline form' do
76126
def expect_inline_admonition(text)

0 commit comments

Comments
 (0)