Switch ES plugins docs to Asciidoctor #796
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Switches the ES "Plugins and Integrations" book's documentation build core from the unmaintained AsciiDoc project to the actively maintained Asciidoctor project. It also speeds up building it by a factor of about 2.5.
Member
Author
|
Here is my hand-curated diff that will be made to the built docs after merging this file! There are quite a few things that I'll have to fix before merging. _other_command_line_parameters.html: -AsciiDoc
+Asciidoctor
@@ -592,7 +592,7 @@
scripts supports a number of other command line parameters:
</p>
<h3>
- <a id="_silent_verbose_mode">
+ <a id="_silentverbose_mode">
</a>
Silent/Verbose mode
<a class="edit_me" href="https://github.com/elastic/elasticsearch/edit/5.0/docs/plugins/plugin-script.asciidoc" rel="nofollow" title="Edit this page on GitHub">These are becoming fairly common in conversions to Asciidoctor. I think we're ok with them, but I still feel bad. There are a few like this that show up in the diff but I won't include them here to keep from repeating myself. mapper.html: -AsciiDoc
+Asciidoctor
@@ -602,27 +602,17 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 5.0.0
- </span>
- ]
- <span class="detail">
- Deprecated in 5.0.0. The
- <code class="literal">
- mapper-attachments
- </code>
- plugin has been replaced by the
- <a class="link" href="ingest-attachment.html" title="Ingest Attachment Processor Plugin">
- <code class="literal">
- ingest-attachment
- </code>
- </a>
- plugin
- </span>
- </span>
- : The mapper-attachments integrates
+ deprecated::[5.0.0,The
+ <code class="literal">
+ mapper-attachments
+ </code>
+ plugin has been replaced by the
+ <a class="link" href="ingest-attachment.html" title="Ingest Attachment Processor Plugin">
+ <code class="literal">
+ ingest-attachment
+ </code>
+ </a>
+ plugin]: The mapper-attachments integrates
<a class="ulink" href="http://lucene.apache.org/tika/" target="_top">
Apache Tika
</a>I'll fix this one before merging. mapper-attachments.html: -AsciiDoc
+Asciidoctor
@@ -597,13 +597,7 @@
<code class="literal">
mapper-attachments
</code>
- plugin has been replaced by the
- <a class="link" href="ingest-attachment.html" title="Ingest Attachment Processor Plugin">
- <code class="literal">
- ingest-attachment
- </code>
- </a>
- plugin
+ plugin has been replaced by the <<ingest-attachment
</p>
</div>
</div>I'll fix this before merging. repository-s3-testing.html: -AsciiDoc
+Asciidoctor
@@ -610,12 +610,12 @@
remote-bucket:
bucket: <bucket in other region>
region: <region>
- external-bucket:
- bucket: <bucket>
- access_key: <access key>
- secret_key: <secret key>
- endpoint: <endpoint>
- protocol: <protocol></pre>
+ external-bucket:
+ bucket: <bucket>
+ access_key: <access key>
+ secret_key: <secret key>
+ endpoint: <endpoint>
+ protocol: <protocol></pre>
</div>
<p>
Replace all occurrences ofTabs coming through again. These are fine. There are some other like this that I won't include. discovery-azure-classic-long.html: -AsciiDoc
+Asciidoctor
@@ -626,7 +626,7 @@
OpenSSL that isn’t from MacPorts, specifically
<code class="literal">
OpenSSL 1.0.1f 6 Jan
- 2014
+ 2014
</code>
doesn’t seem to create a valid keypair for ssh. FWIW,
<code class="literal">Different spacing. Should ok. analysis-icu-collation.html: -AsciiDoc
+Asciidoctor
@@ -602,7 +602,15 @@
, which is a best-effort attempt at language-neutral sorting.
</p>
<p>
- Below is an example of how to set up a field for sorting German names in “phonebook” order:
+ Below is an example of how to set up a field for sorting German names in
+ <span class="quote">
+ “
+ <span class="quote">
+ phonebook
+ </span>
+ ”
+ </span>
+ order:
</p>
<div class="pre_wrapper">
<pre class="programlisting prettyprint lang-console">PUT /my_indexThis one is fine to ignore as well. I won't list others like it to save space. plugin-authors.html: -AsciiDoc
+Asciidoctor
@@ -974,8 +974,10 @@
### mandatory elements for all meta plugins:
#
# 'description': simple summary of the meta plugin
-#
-# 'name': the meta plugin name</pre>
+description=${description}
+#
+# 'name': the meta plugin name
+name=${name}</pre>
</div>
<p>
A meta plugin can be installed/removed like a normal plugin with theThis is a net improvement! alerting.html: -AsciiDoc
+Asciidoctor
@@ -602,17 +602,7 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0. The standalone Watcher plugin will be replaced by the X-Pack in 5.0.0
- </span>
- </span>
- Watcher is the alerting and notification product for Elasticsearch that lets you take action based on changes in your data. It is designed around the principle that if you can query something in Elasticsearch, you can alert on it. Simply define a query, condition, schedule, and the actions to take, and Watcher will do the rest.
+ deprecated::[2.3.0,The standalone Watcher plugin will be replaced by the X-Pack in 5.0.0] Watcher is the alerting and notification product for Elasticsearch that lets you take action based on changes in your data. It is designed around the principle that if you can query something in Elasticsearch, you can alert on it. Simply define a query, condition, schedule, and the actions to take, and Watcher will do the rest.
</dd>
</dl>
</div>I'll fix this before merging. intro.html: -AsciiDoc
+Asciidoctor
@@ -587,7 +587,7 @@
Deprecated in 2.3.0.
</h3>
<p>
- Site plugins and mixed plugins are deprecated and will be removed in 5.0.0. Instead, site plugins should either be migrated to Kibana or should use a standalone web server
+ Site plugins and mixed plugins are deprecated and will be removed in 5.0.0. Instead
</p>
</div>
</div>
@@ -611,17 +611,7 @@
</dt>
<dd>
<p class="simpara">
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0.
- </span>
- </span>
- These plugins contain static web content like Javascript, HTML, and CSS files, that can be served directly from Elasticsearch. Site plugins may only need to be installed on one node, and do not require a restart to become visible. The content of site plugins is accessible via a URL like:
+ deprecated::[2.3.0] These plugins contain static web content like Javascript, HTML, and CSS files, that can be served directly from Elasticsearch. Site plugins may only need to be installed on one node, and do not require a restart to become visible. The content of site plugins is accessible via a URL like:
</p>
<pre class="literallayout">http://yournode:9200/_plugin/[plugin name]</pre>
</dd>I'll figure these out before merging. installation.html: -AsciiDoc
+Asciidoctor
@@ -696,7 +696,11 @@
<code class="literal">
artifactId
</code>
- . For plugin from Sonatype, run:
+ . For instance, to install the {plugins}/mapper-attachments.html[
+ <code class="literal">
+ mapper-attachments
+ </code>
+ ] plugin from Sonatype, run:
</p>
<div class="pre_wrapper">
<pre class="programlisting prettyprint lang-shell">sudo bin/plugin install org.elasticsearch.plugin/mapper-attachments/3.0.0 <a id="CO2-1"></a><span><img alt="" src="images/icons/callouts/1.png"/></span></pre>I'll fix it before merging. security.html: -AsciiDoc
+Asciidoctor
@@ -602,17 +602,7 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0. The standalone Shield plugin will be replaced by the X-Pack in 5.0.0
- </span>
- </span>
- Shield is the Elastic product that makes it easy for anyone to add enterprise-grade security to their ELK stack. Designed to address the growing security needs of thousands of enterprises using ELK today, Shield provides peace of mind when it comes to protecting your data.
+ deprecated::[2.3.0,The standalone Shield plugin will be replaced by the X-Pack in 5.0.0] Shield is the Elastic product that makes it easy for anyone to add enterprise-grade security to their ELK stack. Designed to address the growing security needs of thousands of enterprises using ELK today, Shield provides peace of mind when it comes to protecting your data.
</dd>
</dl>
</div>I'll fix this before merging. repository-gcs-repository.html: -AsciiDoc
+Asciidoctor
@@ -710,10 +710,7 @@
</span>
]
<span class="detail">
- Deprecated in 6.3.0. This setting is now defined in the
- <a class="link" href="repository-gcs-client.html" title="Client Settings">
- client settings
- </a>
+ Deprecated in 6.3.0. This setting is now defined in the <<repository-gcs-client
</span>
</span>
Name used by the client when it uses the Google Cloud Storage service.I'll fix this before merging. analysis-nori-tokenizer.html: -AsciiDoc
+Asciidoctor
@@ -761,7 +761,11 @@
</code>
) followed by its decomposition:
<code class="literal">
- 세종` and `시
+ 세종
+ </code>
+ and
+ <code class="literal">
+ 시
</code>
.
</p>This one is better in Asciidoctor than AsciiDoc. Great! management.html: -AsciiDoc
+Asciidoctor
@@ -590,7 +590,7 @@
Deprecated in 2.3.0.
</h3>
<p>
- Site plugins are deprecated and will be removed in 5.0.0. Instead, site plugins should either be migrated to Kibana or should use a standalone web server.
+ Site plugins are deprecated and will be removed in 5.0.0. Instead
</p>
</div>
</div>
@@ -615,17 +615,7 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0. The standalone Marvel plugin will be replaced by the X-Pack in 5.0.0
- </span>
- </span>
- Marvel is a management and monitoring product for Elasticsearch. Marvel aggregates cluster wide statistics and events and offers a single interface to view and analyze them. Marvel is free for development use but requires a license to run in production.
+ deprecated::[2.3.0,The standalone Marvel plugin will be replaced by the X-Pack in 5.0.0] Marvel is a management and monitoring product for Elasticsearch. Marvel aggregates cluster wide statistics and events and offers a single interface to view and analyze them. Marvel is free for development use but requires a license to run in production.
</dd>
<dt>
<span class="term">I'll fix these before merging. discovery-azure-classic-long.html: -AsciiDoc
+Asciidoctor
@@ -1028,6 +1028,7 @@
"cluster_name" : "elasticsearch",
"cluster_uuid" : "AT69_T_DTp-1qgIJlatQqA",
"version" : {
+ "number" : "{version_qualified}",
"build_flavor" : "default",
"build_type" : "tar",
"build_hash" : "f27399d",This one is wrong is broken in both AsciiDoc and Asciidoctor. I'll fix it before merging. |
Closed
Member
Author
|
I opened #799 to cover some of these issues. |
Member
Author
|
I ran the diff again and I fixed a few of these by pushing small patches: intro.html: - AsciiDoc
+ Asciidoctor
@@ -587,7 +587,7 @@
Deprecated in 2.3.0.
</h3>
<p>
- Site plugins and mixed plugins are deprecated and will be removed in 5.0.0. Instead, site plugins should either be migrated to Kibana or should use a standalone web server
+ Site plugins and mixed plugins are deprecated and will be removed in 5.0.0. Instead
</p>
</div>
</div>I pushed elastic/elasticsearch@80c9237 to fix it. management.html: - AsciiDoc
+ Asciidoctor
@@ -590,7 +590,7 @@
Deprecated in 2.3.0.
</h3>
<p>
- Site plugins are deprecated and will be removed in 5.0.0. Instead, site plugins should either be migrated to Kibana or should use a standalone web server.
+ Site plugins are deprecated and will be removed in 5.0.0. Instead
</p>
</div>
</div>I pushed elastic/elasticsearch@6cdf1c9 to fix this. These issue remain: mapper.html: - AsciiDoc
+ Asciidoctor
@@ -613,13 +613,7 @@
<code class="literal">
mapper-attachments
</code>
- plugin has been replaced by the
- <a class="link" href="ingest-attachment.html" title="Ingest Attachment Processor Plugin">
- <code class="literal">
- ingest-attachment
- </code>
- </a>
- plugin
+ plugin has been replaced by the <<ingest-attachment
</span>
</span>
: The mapper-attachments integrates
mapper-attachments.html:
```patch
- AsciiDoc
+ Asciidoctor
@@ -597,13 +597,7 @@
<code class="literal">
mapper-attachments
</code>
- plugin has been replaced by the
- <a class="link" href="ingest-attachment.html" title="Ingest Attachment Processor Plugin">
- <code class="literal">
- ingest-attachment
- </code>
- </a>
- plugin
+ plugin has been replaced by the <<ingest-attachment
</p>
</div>
</div>
alerting.html:
```patch
- AsciiDoc
+ Asciidoctor
@@ -602,17 +602,7 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0. The standalone Watcher plugin will be replaced by the X-Pack in 5.0.0
- </span>
- </span>
- Watcher is the alerting and notification product for Elasticsearch that lets you take action based on changes in your data. It is designed around the principle that if you can query something in Elasticsearch, you can alert on it. Simply define a query, condition, schedule, and the actions to take, and Watcher will do the rest.
+ deprecated::[2.3.0,The standalone Watcher plugin will be replaced by the X-Pack in 5.0.0] Watcher is the alerting and notification product for Elasticsearch that lets you take action based on changes in your data. It is designed around the principle that if you can query something in Elasticsearch, you can alert on it. Simply define a query, condition, schedule, and the actions to take, and Watcher will do the rest.
</dd>
</dl>
</div>
installation.html:
```patch
- AsciiDoc
+ Asciidoctor
@@ -696,7 +696,11 @@
<code class="literal">
artifactId
</code>
- . For plugin from Sonatype, run:
+ . For instance, to install the {plugins}/mapper-attachments.html[
+ <code class="literal">
+ mapper-attachments
+ </code>
+ ] plugin from Sonatype, run:
</p>
<div class="pre_wrapper">
<pre class="programlisting prettyprint lang-shell">sudo bin/plugin install org.elasticsearch.plugin/mapper-attachments/3.0.0 <a id="CO2-1"></a><span><img alt="" src="images/icons/callouts/1.png"/></span></pre>management.html: - AsciiDoc
+ Asciidoctor
@@ -615,17 +615,7 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0. The standalone Marvel plugin will be replaced by the X-Pack in 5.0.0
- </span>
- </span>
- Marvel is a management and monitoring product for Elasticsearch. Marvel aggregates cluster wide statistics and events and offers a single interface to view and analyze them. Marvel is free for development use but requires a license to run in production.
+ deprecated::[2.3.0,The standalone Marvel plugin will be replaced by the X-Pack in 5.0.0] Marvel is a management and monitoring product for Elasticsearch. Marvel aggregates cluster wide statistics and events and offers a single interface to view and analyze them. Marvel is free for development use but requires a license to run in production.
</dd>
<dt>
<span class="term">security.html: - AsciiDoc
+ Asciidoctor
@@ -602,17 +602,7 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 2.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 2.3.0. The standalone Shield plugin will be replaced by the X-Pack in 5.0.0
- </span>
- </span>
- Shield is the Elastic product that makes it easy for anyone to add enterprise-grade security to their ELK stack. Designed to address the growing security needs of thousands of enterprises using ELK today, Shield provides peace of mind when it comes to protecting your data.
+ deprecated::[2.3.0,The standalone Shield plugin will be replaced by the X-Pack in 5.0.0] Shield is the Elastic product that makes it easy for anyone to add enterprise-grade security to their ELK stack. Designed to address the growing security needs of thousands of enterprises using ELK today, Shield provides peace of mind when it comes to protecting your data.
</dd>
</dl>
</div>repository-gcs-repository.html: - AsciiDoc
+ Asciidoctor
@@ -703,20 +703,11 @@
</span>
</dt>
<dd>
- <span class="deprecated">
- [
- <span class="version">
- 6.3.0
- </span>
- ]
- <span class="detail">
- Deprecated in 6.3.0. This setting is now defined in the
- <a class="link" href="repository-gcs-client.html" title="Client Settings">
- client settings
- </a>
- </span>
- </span>
- Name used by the client when it uses the Google Cloud Storage service.
+ deprecated::[6.3.0, This setting is now defined in the
+ <a class="link" href="repository-gcs-client.html" title="Client Settings">
+ client settings
+ </a>
+ ] Name used by the client when it uses the Google Cloud Storage service.
</dd>
</dl>
</div> |
Member
Author
|
I don't believe I can fix the remaining issues in an AsciiDoc and Asciidoctor compatible way. I'd be ok with switching and then pushing fixes for these differences. @lcawl, how would you feel about that? |
Contributor
|
@nik9000 That seems acceptable to me. If you want help implementing or backporting the fixes, just let me know! |
Member
Author
|
Thanks for reviewing and confirming my plan! I've merged and I've pushed docs fixes for the problem above. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Switches the ES "Plugins and Integrations" book's documentation build
core from the unmaintained AsciiDoc project to the actively maintained
Asciidoctor project. It also speeds up building it by a factor of about
2.5.