Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Asciidoctor: Implement beta and experimental #662

Merged
merged 4 commits into from
Mar 5, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 30 additions & 20 deletions README.asciidoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,15 @@
= Docs HOWTO
:ref: http://www.elastic.co/guide/elasticsearch/reference/current

////
This file contains the sequence `_` to escape from around Elastic's
Asciidoctor plugin that provides Asciidoc compatibility. It automatically
translates things like `beta[]` into their Asciidoctor compatible form
which looks like `beta::[]`. We use `beta_]` inside of asciidoc
examples so we can output `beta[]`. Once we no longer support Asciidoc
we can drop these sequences.
////

== Conditions of use

This documentation build process is provided to the public purely for the
@@ -1233,9 +1242,9 @@ the addition or deprecation of individual parameters.
[source,asciidoc]
----------------------------------
[horizontal]
`foo.bar`:: Does XYZ. added[0.90.4]
`foo.bar`:: Does XYZ. coming[0.90.4]
`foo.baz`:: Does XYZ. deprecated[0.90.4]
`foo.bar`:: Does XYZ. added_0.90.4]
`foo.bar`:: Does XYZ. coming_0.90.4]
`foo.baz`:: Does XYZ. deprecated_0.90.4]
----------------------------------

[horizontal]
@@ -1250,9 +1259,9 @@ user hovers over it:
[source,asciidoc]
----------------------------------
[horizontal]
`foo.bar`:: Does XYZ. added[0.90.4,Replaces `foo.baz`]
`foo.bar`:: Does XYZ. coming[0.90.4,Replaces `foo.baz`]
`foo.baz`:: Does XYZ. deprecated[0.90.4,Replaced by `foo.bar`]
`foo.bar`:: Does XYZ. added_0.90.4,Replaces `foo.baz`]
`foo.bar`:: Does XYZ. coming_0.90.4,Replaces `foo.baz`]
`foo.baz`:: Does XYZ. deprecated_0.90.4,Replaced by `foo.bar`]
----------------------------------

[horizontal]
@@ -1270,19 +1279,19 @@ to the version in which the change was made:
----------------------------------
==== New section
added[0.90.4]
added_0.90.4]
Text about new functionality...
==== New section not yet released
coming[0.90.9]
coming_0.90.9]
Text about new functionality...
==== Old section
deprecated[0.90.4]
deprecated_0.90.4]
Text about old functionality...
----------------------------------
@@ -1305,6 +1314,7 @@ deprecated[0.90.4]

Text about old functionality...

[[with_details]]
==== With details...

Or they can include extra text, including more
@@ -1315,21 +1325,21 @@ Asciidoc markup:
[[new-section]]
==== New section
added[0.90.4,Replaces `foo.bar`. See <<old-section>>]
added&#x5f;0.90.4,Replaces `foo.bar`. See <<old-section>>]
Text about new functionality...
[[coming-section]]
==== New section not yet released
coming[0.90.9,Replaces `foo.bar`. See <<old-section>>]
coming&#x5f;0.90.9,Replaces `foo.bar`. See <<old-section>>]
Text about new functionality...
[[old-section]]
==== Old section
deprecated[0.90.4,Replace by `foo.baz`. See <<new-section>>]
deprecated&#x5f;0.90.4,Replace by `foo.baz`. See <<new-section>>]
Text about old functionality...
----------------------------------
@@ -1359,9 +1369,9 @@ markup similar to that used in <<changes>>. For instance:
[[new-feature]]
=== New experimental feature
experimental[]
experimental&#x5f;]
experimental[Custom text goes here]
experimental&#x5f;Custom text goes here]
Text about new feature...
@@ -1373,8 +1383,8 @@ a new experimental parameter:
[horizontal]
`established_param`:: This param has been around for ages and won't change.
`experimental_param`:: experimental[] This param is experimental and may change in the future.
`experimental_param`:: experimental[Custom text goes here] This param is experimental and may change in the future.
`experimental_param`:: experimental&#x5f;] This param is experimental and may change in the future.
`experimental_param`:: experimental&#x5f;Custom text goes here] This param is experimental and may change in the future.
----------------------------------

@@ -1403,9 +1413,9 @@ a new experimental parameter:
[[new-beta-feature]]
=== New beta feature
beta[]
beta&#x5f;]
beta[Custom text goes here]
beta&#x5f;Custom text goes here]
Text about new feature...
@@ -1417,8 +1427,8 @@ a new beta parameter:
[horizontal]
`established_param`:: This param has been around for ages and won't change.
`beta_param`:: beta[] This param is beta and may change in the future.
`beta_param`:: beta[Custom text goes here] This param is beta and may change in the future.
`beta_param`:: beta&#x5f;] This param is beta and may change in the future.
`beta_param`:: beta&#x5f;Custom text goes here] This param is beta and may change in the future.
----------------------------------

19 changes: 18 additions & 1 deletion integtest/Makefile
Original file line number Diff line number Diff line change
@@ -12,6 +12,8 @@ check: \
style \
minimal_expected_files minimal_same_files \
includes_expected_files includes_same_files \
beta_expected_files beta_same_files \
experimental_expected_files experimental_same_files \
readme_expected_files readme_same_files \
small_all_expected_files

@@ -41,6 +43,16 @@ readme_expected_files: /tmp/readme_asciidoc
[ -s $^/images/icons/callouts/2.png ]
[ -s $^/snippets/blocks/1.json ]

.PHONY: experimental_expected_files
beta_expected_files: /tmp/beta_asciidoc
$(STANDARD_EXPECTED_FILES)
[ -s $^/images/icons/warning.png ]

.PHONY: experimental_expected_files
experimental_expected_files: /tmp/experimental_asciidoc
$(STANDARD_EXPECTED_FILES)
[ -s $^/images/icons/warning.png ]

.PHONY: %_expected_files
%_expected_files: /tmp/%_asciidoc
$(STANDARD_EXPECTED_FILES)
@@ -54,7 +66,7 @@ readme_expected_files: /tmp/readme_asciidoc
<(cd /tmp/$*_asciidoctor && find * -type f | sort)
# The grep -v below are for known issues with asciidoctor
for file in $$(cd /tmp/$*_asciidoc && find * -type f -name '*.html' \
| grep -v 'blocks\|changes\|experimental'); do \
| grep -v 'blocks'); do \
./html_diff /tmp/$*_asciidoc/$$file /tmp/$*_asciidoctor/$$file; \
done

@@ -67,6 +79,11 @@ endef

/tmp/readme_asciidoctor: /docs_build/README.asciidoc
$(BD) --asciidoctor --doc /docs_build/README.asciidoc
# These are different when rendered by asciidoctor but they are
# correct for asciidoctor. So we're ok with it. It isn't perfect, but
# perfect is quite hard for this.
# sed -i -E 's/beta::?\[/beta\[/' /tmp/readme_asciidoctor/experimental.html
# sed -i -E 's/experimental::?\[/experimental\[/' /tmp/readme_asciidoctor/experimental.html

# These don't declare dependencies because we don't know in general which files
# are needed to build which asciidoc files.
7 changes: 7 additions & 0 deletions integtest/beta.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
= Title

== Chapter

beta[]

Words
7 changes: 7 additions & 0 deletions integtest/experimental.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
= Title

== Chapter

experimental[]

Words
2 changes: 1 addition & 1 deletion lib/ES/Template.pm
Original file line number Diff line number Diff line change
@@ -154,7 +154,7 @@ sub _init {
}

my $created = $1 || 0;
if ( not $force and time - $latest < 20 * 60 ) {
if ( not $force and time - $latest < 20 * 60) {
$new = $old[-1];
}
else {
74 changes: 74 additions & 0 deletions resources/asciidoctor/lib/care_admonition/extension.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# frozen_string_literal: true

require 'asciidoctor/extensions'

##
# Extensions for marking when something as `beta` or `experimental`.
#
# Usage
#
# beta::[]
# experimental::[]
# Foo beta:[]
# Foo experimental:[]
#
class CareAdmonition < Asciidoctor::Extensions::Group
def activate(registry)
[
[:beta, 'beta'],
[:experimental, 'experimental'],
].each do |(name, role)|
registry.block_macro ChangeAdmonitionBlock.new(role), name
registry.inline_macro ChangeAdmonitionInline.new(role), name
end
end

##
# Block care admonition.
class ChangeAdmonitionBlock < Asciidoctor::Extensions::BlockMacroProcessor
use_dsl
name_positional_attributes :passtext

def initialize(role)
super(nil)
@role = role
end

def process(parent, _target, attrs)
Asciidoctor::Block.new(parent, :admonition,
:source => attrs[:passtext],
:attributes => {
'role' => @role,
'name' => 'warning',
'style' => 'warning',
})
end
end

##
# Inline care admonition.
class ChangeAdmonitionInline < Asciidoctor::Extensions::InlineMacroProcessor
use_dsl
name_positional_attributes :text
with_format :short

def initialize(role)
super(nil)
@role = role
end

def process(_parent, _target, attrs)
if attrs[:text]
<<~DOCBOOK
<phrase role="#{@role}">
#{attrs[:text]}
</phrase>
DOCBOOK
else
<<~DOCBOOK
<phrase role="#{@role}"/>
DOCBOOK
end
end
end
end
Original file line number Diff line number Diff line change
@@ -142,7 +142,7 @@ def reader.process_line(line)
@code_block_start = line
end
end
supported = 'added|coming|deprecated'
supported = 'added|beta|coming|deprecated|experimental'
# First convert the "block" version of these macros. We convert them
# to block macros because they are at the start of the line....
line&.gsub!(/^(#{supported})\[([^\]]*)\]/, '\1::[\2]')
2 changes: 2 additions & 0 deletions resources/asciidoctor/lib/extensions.rb
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# frozen_string_literal: true

require_relative 'care_admonition/extension'
require_relative 'change_admonition/extension'
require_relative 'copy_images/extension'
require_relative 'cramped_include/extension'
@@ -8,6 +9,7 @@
require_relative 'elastic_compat_preprocessor/extension'
require_relative 'elastic_include_tagged/extension'

Asciidoctor::Extensions.register CareAdmonition
Asciidoctor::Extensions.register ChangeAdmonition
Asciidoctor::Extensions.register do
# Enable storing the source locations so we can look at them. This is required
113 changes: 113 additions & 0 deletions resources/asciidoctor/spec/care_admonition_spec.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# frozen_string_literal: true

require 'care_admonition/extension'

RSpec.describe CareAdmonition do
before(:each) do
Asciidoctor::Extensions.register CareAdmonition
end

after(:each) do
Asciidoctor::Extensions.unregister_all
end

%w[beta experimental].each do |(name)|
it "#{name}'s block version creates a warning" do
actual = convert <<~ASCIIDOC
== Example
#{name}::[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<warning role="#{name}">
<simpara></simpara>
</warning>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "#{name}'s block version supports asciidoc in the passtext" do
actual = convert <<~ASCIIDOC
== Example
#{name}::[See <<some-reference>>]
[[some-reference]]
=== Some Reference
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<warning role="#{name}">
<simpara>See <xref linkend="some-reference"/></simpara>
</warning>
<section id="some-reference">
<title>Some Reference</title>
</section>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "#{name}'s block version is not invoked without the ::" do
actual = convert <<~ASCIIDOC
== Example
#{name}[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<simpara>#{name}[]</simpara>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "#{name}'s inline version creates a phrase" do
actual = convert <<~ASCIIDOC
== Example
words #{name}:[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<simpara>words <phrase role="#{name}"/>
</simpara>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "#{name}'s inline version creates a phrase with extra text if provided" do
actual = convert <<~ASCIIDOC
== Example
words #{name}:[more words]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<simpara>words <phrase role="#{name}">
more words
</phrase>
</simpara>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "#{name}'s inline version is not invoked without the :" do
actual = convert <<~ASCIIDOC
== Example
words #{name}[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<simpara>words #{name}[]</simpara>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end
end
end
22 changes: 22 additions & 0 deletions resources/asciidoctor/spec/copy_images_spec.rb
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# frozen_string_literal: true

require 'care_admonition/extension'
require 'change_admonition/extension'
require 'copy_images/extension'
require 'fileutils'
@@ -9,6 +10,7 @@
RSpec::Matchers.define_negated_matcher :not_match, :match

before(:each) do
Asciidoctor::Extensions.register CareAdmonition
Asciidoctor::Extensions.register ChangeAdmonition
Asciidoctor::Extensions.register do
tree_processor CopyImages::CopyImages
@@ -419,6 +421,26 @@ def copy_attributes(copied)
end
end

%w[beta experimental].each do |(name)|
it "copies images for the block formatted #{name} care admonition when requested" do
copied = []
attributes = copy_attributes copied
attributes['copy-admonition-images'] = 'png'
input = <<~ASCIIDOC
#{name}::[]
ASCIIDOC
# We can't get the location of the blocks because asciidoctor doesn't
# make it available to us here!
expected_warnings = <<~WARNINGS
INFO: <stdin>: line 1: copying #{spec_dir}/resources/copy_images/images/icons/warning.png
WARNINGS
convert input, attributes, eq(expected_warnings.strip)
expect(copied).to eq([
["images/icons/warning.png", "#{spec_dir}/resources/copy_images/images/icons/warning.png"],
])
end
end

[
%w[added note],
%w[coming note],
76 changes: 64 additions & 12 deletions resources/asciidoctor/spec/elastic_compat_preprocessor_spec.rb
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# frozen_string_literal: true

require 'care_admonition/extension'
require 'change_admonition/extension'
require 'elastic_compat_preprocessor/extension'
require 'elastic_include_tagged/extension'
require 'shared_examples/does_not_break_line_numbers'

RSpec.describe ElasticCompatPreprocessor do
before(:each) do
Asciidoctor::Extensions.register CareAdmonition
Asciidoctor::Extensions.register ChangeAdmonition
Asciidoctor::Extensions.register do
preprocessor ElasticCompatPreprocessor
@@ -57,21 +59,71 @@
end

it "doesn't mind skipped #{name} block macros" do
actual = convert <<~ASCIIDOC
== Example
actual = convert <<~ASCIIDOC
== Example
ifeval::["true" == "false"]
#{name}[some_version]
#endif::[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
ifeval::["true" == "false"]
#{name}[some_version]
#endif::[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end
end

%w[beta experimental].each do |name|
it "invokes the #{name} block macro when #{name}[] starts a line" do
actual = convert <<~ASCIIDOC
== Example
#{name}[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<warning role="#{name}">
<simpara></simpara>
</warning>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "invokes the #{name} inline macro when #{name}[version] is otherwise on the line" do
actual = convert <<~ASCIIDOC
== Example
words #{name}[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
<simpara>words <phrase role="#{name}"/>
</simpara>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end

it "doesn't mind skipped #{name} block macros" do
actual = convert <<~ASCIIDOC
== Example
ifeval::["true" == "false"]
#{name}[]
#endif::[]
ASCIIDOC
expected = <<~DOCBOOK
<chapter id="_example">
<title>Example</title>
</chapter>
DOCBOOK
expect(actual).to eq(expected.strip)
end
end

it "invokes include-tagged::" do