You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2019/10/14 19:46:33 UTC
[lucene-solr] branch jira/solr-12786 updated: Update versions for
ref guide build tooling; fix pages that fail validation;
replace pygments with rouge
This is an automated email from the ASF dual-hosted git repository.
ctargett pushed a commit to branch jira/solr-12786
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git
The following commit(s) were added to refs/heads/jira/solr-12786 by this push:
new 3f6d2c9 Update versions for ref guide build tooling; fix pages that fail validation; replace pygments with rouge
3f6d2c9 is described below
commit 3f6d2c9514f5b8680f4d280d5efe5593425e62c2
Author: Cassandra Targett <ca...@lucidworks.com>
AuthorDate: Mon Oct 14 14:43:36 2019 -0500
Update versions for ref guide build tooling; fix pages that fail validation; replace pygments with rouge
---
dev-tools/scripts/jenkins.build.ref.guide.sh | 9 ++++----
lucene/ivy-versions.properties | 7 +++---
solr/solr-ref-guide/README.adoc | 26 +++++++++++++---------
solr/solr-ref-guide/src/_config.yml.template | 4 ++--
.../src/basic-authentication-plugin.adoc | 2 +-
.../src/common-query-parameters.adoc | 2 +-
solr/solr-ref-guide/src/enabling-ssl.adoc | 2 +-
.../src/kerberos-authentication-plugin.adoc | 2 +-
solr/solr-ref-guide/src/metrics-reporting.adoc | 6 ++---
.../src/resource-and-plugin-loading.adoc | 2 +-
.../setting-up-an-external-zookeeper-ensemble.adoc | 6 ++---
.../src/solr-control-script-reference.adoc | 6 ++---
solr/solr-ref-guide/src/solr-tutorial.adoc | 2 +-
.../src/solrcloud-autoscaling-api.adoc | 4 ++--
.../src/solrcloud-autoscaling-triggers.adoc | 4 ++--
...ng-zookeeper-to-manage-configuration-files.adoc | 2 +-
16 files changed, 45 insertions(+), 41 deletions(-)
diff --git a/dev-tools/scripts/jenkins.build.ref.guide.sh b/dev-tools/scripts/jenkins.build.ref.guide.sh
index f1a8bdb..e91c240 100755
--- a/dev-tools/scripts/jenkins.build.ref.guide.sh
+++ b/dev-tools/scripts/jenkins.build.ref.guide.sh
@@ -60,11 +60,10 @@ echoRun "rvm $RUBY_VERSION@$GEMSET" # Activate this project's gemset
# Install gems in the gemset. Param --force disables dependency conflict detection.
echoRun "gem install --force --version 3.5.0 jekyll"
-echoRun "gem uninstall --all --ignore-dependencies asciidoctor" # Get rid of all versions
-echoRun "gem install --force --version 1.5.6.2 asciidoctor"
-echoRun "gem install --force --version 2.1.0 jekyll-asciidoc"
-echoRun "gem install --force --version 1.1.2 pygments.rb"
-echoRun "gem install --force --version 3.0.9 slim"
+echoRun "gem install --force --version 3.0.0 jekyll-asciidoc"
+echoRun "gem install --force --version 4.0.1 slim"
+echoRun "gem install --force --version 2.0.10 tilt"
+echoRun "gem install --force --version 1.1.5 concurrent-ruby"
cd solr/solr-ref-guide
diff --git a/lucene/ivy-versions.properties b/lucene/ivy-versions.properties
index e5a4a8a..959d81b 100644
--- a/lucene/ivy-versions.properties
+++ b/lucene/ivy-versions.properties
@@ -215,9 +215,10 @@ org.apache.zookeeper.version = 3.5.5
/org.apache.zookeeper/zookeeper = ${org.apache.zookeeper.version}
/org.apache.zookeeper/zookeeper-jute = ${org.apache.zookeeper.version}
-# v1.6.0-alpha.5 of asciidoctor-ant includes asciidoctorj-pdf 1.5.0-alpha.16,
-# which is the same as asciidoctor-pdf 1.5.0-alpha.16
-/org.asciidoctor/asciidoctor-ant = 1.6.0-alpha.5
+# v1.6.2 of asciidoctor-ant includes asciidoctorj 1.6.2, which uses
+# asciidoctor 1.5.8, and asciidoctorj-pdf 1.5.0-alpha.16, which is the same
+# as asciidoctor-pdf 1.5.0-alpha.16
+/org.asciidoctor/asciidoctor-ant = 1.6.2
/org.aspectj/aspectjrt = 1.8.0
diff --git a/solr/solr-ref-guide/README.adoc b/solr/solr-ref-guide/README.adoc
index d485b99..61afa4f 100644
--- a/solr/solr-ref-guide/README.adoc
+++ b/solr/solr-ref-guide/README.adoc
@@ -23,17 +23,21 @@ Raw content is stored in Asciidoc (`.adoc`) formatted files in the `src/` direct
== Prerequisites for Building
These files are processed with AsciiDoctor in 2 different ways:
-* Via Jekyll to build an HTML browsable version of the Ref Guide.
-** Prerequisites: `Ruby` (v2.1 or higher) and the following gems must be installed:
-*** `jekyll`: v3.5, not v4.x. Use `gem install jekyll --force --version 3.5.0` to force install of Jekyll 3.5.0.
-*** `asciidoctor`: v1.5.6.2, not 1.5.7 or higher. Use `gem install asciidoctor --force --version 1.5.6.2`. NOTE: You must do this before installing `jekyll-asciidoc` or you'll get a version of Asciidoctor that we can't use yet.
-*** `jekyll-asciidoc`: v2.1 or higher. Use `gem install jekyll-asciidoc` to install.
-*** `pygments.rb`: v1.1.2 or higher. Use `gem install pygments.rb` to install.
-// The following is only necessary until we are on Asciidoctor 1.5.8 or higher.
-// See https://github.com/asciidoctor/asciidoctor/issues/2928 for details of the problem with Slim 4.x and higher.
-*** `slim`: v3.0.1 or higher, only to 3.0.9. Do *NOT* use Slim 4.x. Use `gem install slim --force --version 3.0.9` to install.
-* Via `asciidoctor-ant` to build the officially released PDF version of the Ref Guide.
-** Prerequisites: None beyond those required to use the main Lucene/Solr build: Java, and Ant.
+* HTML version, using Jekyll:
+** `Ruby` (v2.3 or higher)
+** The following gems must be installed:
+*** `jekyll`: v3.5, not v4.x.
+Use `gem install jekyll --force --version 3.5.0` to force install of v3.5.0.
+*** `jekyll-asciidoc`: v2.1 or higher; latest version (3.0.0) is fine.
+Use `gem install jekyll-asciidoc` to install.
+*** `slim`: v3.0 or higher; latest version (4.0.1) is fine.
+Use `gem install slim` to install.
+*** `tilt`: v1.0 or higher; latest version (2.0.10) is fine.
+Use `gem install tilt` to install.
+*** `concurrent-ruby`: v1.0 or higher; latest version (1.1.5) is fine.
+Use `gem install concurrent-ruby` to install.
+* PDF version, via `asciidoctor-ant`:
+** None beyond those required to use the main Lucene/Solr build: Java, and Ant.
== Building the Guide
For details on building the ref guide, see `ant -p`.
diff --git a/solr/solr-ref-guide/src/_config.yml.template b/solr/solr-ref-guide/src/_config.yml.template
index 7c29200..5fc023a 100755
--- a/solr/solr-ref-guide/src/_config.yml.template
+++ b/solr/solr-ref-guide/src/_config.yml.template
@@ -94,7 +94,7 @@ asciidoctor:
<<: *solr-attributes-ref
attribute-missing: "warn"
icons: "font"
- source-highlighter: "pygments"
- pygments-css: "style"
+ source-highlighter: "rouge"
+ rouge-theme: "thankful-eyes"
# NOTE: do *NOT* use an self-empty div tag (ie: <div/>) here - it will break jquery
section-toc: "<div class=\"toc section-toc\"></div>"
diff --git a/solr/solr-ref-guide/src/basic-authentication-plugin.adoc b/solr/solr-ref-guide/src/basic-authentication-plugin.adoc
index 18ad2b8..1bf6192 100644
--- a/solr/solr-ref-guide/src/basic-authentication-plugin.adoc
+++ b/solr/solr-ref-guide/src/basic-authentication-plugin.adoc
@@ -71,7 +71,7 @@ If you are using SolrCloud, you must upload `security.json` to ZooKeeper. You ca
bin/solr zk cp file:path_to_local_security.json zk:/security.json -z localhost:9983
----
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
=== Caveats
diff --git a/solr/solr-ref-guide/src/common-query-parameters.adoc b/solr/solr-ref-guide/src/common-query-parameters.adoc
index aeb77df..0486ff1 100644
--- a/solr/solr-ref-guide/src/common-query-parameters.adoc
+++ b/solr/solr-ref-guide/src/common-query-parameters.adoc
@@ -102,7 +102,7 @@ fq=+popularity:[10 TO *] +section:0
----
* The document sets from each filter query are cached independently. Thus, concerning the previous examples: use a single `fq` containing two mandatory clauses if those clauses appear together often, and use two separate `fq` parameters if they are relatively independent. (To learn about tuning cache sizes and making sure a filter cache actually exists, see <<the-well-configured-solr-instance.adoc#the-well-configured-solr-instance,The Well-Configured Solr Instance>>.)
-* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucene-s-classic-query-parser-and-solr-s-standard-query-parser,filter(condition) syntax>> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries.
+* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucenes-classic-query-parser-and-solrs-standard-query-parser,filter(condition) syntax>> inside the `fq` to cache clauses individually and - among other things - to achieve union of cached filter queries.
* As with all parameters: special characters in an URL need to be properly escaped and encoded as hex values. Online tools are available to help you with URL-encoding. For example: http://meyerweb.com/eric/tools/dencoder/.
diff --git a/solr/solr-ref-guide/src/enabling-ssl.adoc b/solr/solr-ref-guide/src/enabling-ssl.adoc
index 2d9e69c..93cf2ea 100644
--- a/solr/solr-ref-guide/src/enabling-ssl.adoc
+++ b/solr/solr-ref-guide/src/enabling-ssl.adoc
@@ -247,7 +247,7 @@ If you have set up your ZooKeeper cluster to use a <<taking-solr-to-production.a
=== Run SolrCloud with SSL
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from all of the `bin/solr`/`bin\solr.cmd` commands below.
==== Create Solr Home Directories for Two Nodes
diff --git a/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc b/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc
index ed0b3cb..90682be 100644
--- a/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc
+++ b/solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc
@@ -298,7 +298,7 @@ Once the configuration is complete, you can start Solr with the `bin/solr` scrip
bin/solr -c -z server1:2181,server2:2181,server3:2181/solr
----
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
=== Test the Configuration
diff --git a/solr/solr-ref-guide/src/metrics-reporting.adoc b/solr/solr-ref-guide/src/metrics-reporting.adoc
index dafa172..ecefda7 100644
--- a/solr/solr-ref-guide/src/metrics-reporting.adoc
+++ b/solr/solr-ref-guide/src/metrics-reporting.adoc
@@ -87,7 +87,7 @@ The metrics available in your system can be customized by modifying the `<metric
TIP: See also the section <<format-of-solr-xml.adoc#format-of-solr-xml,Format of Solr.xml>> for more information about the `solr.xml` file, where to find it, and how to edit it.
-=== The <metrics><hiddenSysProps> Element
+=== The <metrics> <hiddenSysProps> Element
This section of `solr.xml` allows you to define the system properties which are considered system-sensitive and should not be exposed via the Metrics API.
@@ -106,11 +106,11 @@ If this section is not defined, the following default configuration is used whic
</metrics>
----
-=== The <metrics><reporters> Element
+=== The <metrics> <reporters> Element
Reporters consume the metrics data generated by Solr. See the section <<Reporters>> below for more details on how to configure custom reporters.
-=== The <metrics><suppliers> Element
+=== The <metrics> <suppliers> Element
Suppliers help Solr generate metrics data. The `<metrics><suppliers>` section of `solr.xml` allows you to define your own implementations of metrics and configure parameters for them.
diff --git a/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc b/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc
index 04dc840..6efd135 100644
--- a/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc
+++ b/solr/solr-ref-guide/src/resource-and-plugin-loading.adoc
@@ -46,7 +46,7 @@ CAUTION: By default, ZooKeeper's file size limit is 1MB. If your files are large
Under standalone Solr, when looking up a plugin or resource to be loaded, Solr's resource loader will first look under the `<instanceDir>/conf/` directory. If the plugin or resource is not found, the configured plugin and resource file paths are searched - see the section <<Lib Directives in SolrConfig>> below.
-On core load, Solr's resource loader constructs a list of paths (subdirectories and jars), first under <<solr_home-lib,`solr_home/lib`>>, and then under directories pointed to by <<Lib Directives in SolrConfig,`<lib/>` directives in SolrConfig>>.
+On core load, Solr's resource loader constructs a list of paths (subdirectories and jars), first under <<solr_homelib,`solr_home/lib`>>, and then under directories pointed to by <<Lib Directives in SolrConfig,`<lib/>` directives in SolrConfig>>.
When looking up a resource or plugin to be loaded, the paths on the list are searched in the order they were added.
diff --git a/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc b/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc
index 224dd00..837c4d9 100644
--- a/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc
+++ b/solr/solr-ref-guide/src/setting-up-an-external-zookeeper-ensemble.adoc
@@ -201,7 +201,7 @@ And create the `myid` file in the `/var/lib/zookeeper` directory:
Repeat this for servers 4 and 5 if you are creating a 5-node ensemble (a rare case).
-=== ZooKeeper Environment Configuration
+=== ZooKeeper Environment Configuration
To ease troubleshooting in case of problems with the ensemble later, it's recommended to run ZooKeeper with logging enabled and with proper JVM garbage collection (GC) settings.
@@ -295,9 +295,9 @@ For example, to point the Solr instance to the ZooKeeper you've started on port
bin/solr start -e cloud -z zk1:2181,zk2:2181,zk3:2181/solr
----
-=== Updating Solr's Include Files
+=== Updating Solr Include Files
-If you update Solr's include file (`solr.in.sh` or `solr.in.cmd`), which overrides defaults used with `bin/solr`, you will not have to use the `-z` parameter with `bin/solr` commands.
+If you update Solr include files (`solr.in.sh` or `solr.in.cmd`), which overrides defaults used with `bin/solr`, you will not have to use the `-z` parameter with `bin/solr` commands.
[.dynamic-tabs]
diff --git a/solr/solr-ref-guide/src/solr-control-script-reference.adoc b/solr/solr-ref-guide/src/solr-control-script-reference.adoc
index c3c8e26..fe8a3cc 100644
--- a/solr/solr-ref-guide/src/solr-control-script-reference.adoc
+++ b/solr/solr-ref-guide/src/solr-control-script-reference.adoc
@@ -60,7 +60,7 @@ Start Solr in SolrCloud mode, which will also launch the embedded ZooKeeper inst
+
This option can be shortened to simply `-c`.
+
-If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) or pass the -z parameter.
+If you are already running a ZooKeeper ensemble that you want to use instead of the embedded (single-node) ZooKeeper, you should also either specify `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) or pass the -z parameter.
+
For more details, see the section <<SolrCloud Mode>> below.
+
@@ -172,7 +172,7 @@ The `-c` and `-cloud` options are equivalent:
If you specify a ZooKeeper connection string, such as `-z 192.168.1.4:2181`, then Solr will connect to ZooKeeper and join the cluster.
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from all `bin/solr` commands.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from all `bin/solr` commands.
When starting Solr in SolrCloud mode, if you do not define `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` nor specify the `-z` option, then Solr will launch an embedded ZooKeeper server listening on the Solr port + 1000, i.e., if Solr is running on port 8983, then the embedded ZooKeeper will be listening on port 9983.
@@ -905,4 +905,4 @@ Export all documents from a collection `gettingstarted` to a file called `gettin
*Example: importing the `javabin` files*
-`curl -X POST --header "Content-Type: application/javabin" --data-binary @gettingstarted.javabin http://localhost:8983/solr/gettingstarted/update?commit=true`
\ No newline at end of file
+`curl -X POST --header "Content-Type: application/javabin" --data-binary @gettingstarted.javabin http://localhost:8983/solr/gettingstarted/update?commit=true`
diff --git a/solr/solr-ref-guide/src/solr-tutorial.adoc b/solr/solr-ref-guide/src/solr-tutorial.adoc
index ca88134..77b0deb 100644
--- a/solr/solr-ref-guide/src/solr-tutorial.adoc
+++ b/solr/solr-ref-guide/src/solr-tutorial.adoc
@@ -513,7 +513,7 @@ This starts the first node. When it's done start the second node, and tell it ho
`./bin/solr start -c -p 7574 -s example/cloud/node2/solr -z localhost:9983`
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
=== Create a New Collection
diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
index ed51b1d..b576e74 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
@@ -676,7 +676,7 @@ The `remove-policy` command accepts a policy name to be removed from Solr. The p
If you attempt to remove a policy that is being used by a collection, this command will fail to delete the policy until the collection itself is deleted.
-=== Create/Update Trigger
+=== Create or Update a Trigger
The `set-trigger` command can be used to create a new trigger or overwrite an existing one.
@@ -732,7 +732,7 @@ The `remove-trigger` command can be used to remove a trigger. It accepts a singl
}
----
-=== Create/Update Trigger Listener
+=== Create or Update a Trigger Listener
The `set-listener` command can be used to create or modify a listener for a trigger.
diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc
index bf0953e..de346d8 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc
@@ -55,7 +55,7 @@ generated, which may significantly differ due to the rate limits set by `waitFor
indicates the nodes that were lost or added.
== Trigger Configuration
-Trigger configurations are managed using the <<solrcloud-autoscaling-api.adoc#write-api,Autoscaling Write API>> with the commands `<<solrcloud-autoscaling-api.adoc#create-update-trigger,set-trigger>>`, `<<solrcloud-autoscaling-api.adoc#remove-trigger,remove-trigger>>`,
+Trigger configurations are managed using the <<solrcloud-autoscaling-api.adoc#write-api,Autoscaling Write API>> with the commands `<<solrcloud-autoscaling-api.adoc#create-or-update-a-trigger,set-trigger>>`, `<<solrcloud-autoscaling-api.adoc#remove-trigger,remove-trigger>>`,
`suspend-trigger`, and `resume-trigger`.
=== Trigger Properties
@@ -606,4 +606,4 @@ old markers for such events so that they don't accumulate over time. This trigge
=== `solr.ExecutePlanAction`
This action simply executes any collection admin requests generated by other
actions - in particular, in the default configuration it executes `DELETESHARD` requests produced by
-`solr.InactiveShardPlanAction`, as described above.
\ No newline at end of file
+`solr.InactiveShardPlanAction`, as described above.
diff --git a/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc b/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc
index 546ee99..fe13460 100644
--- a/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc
+++ b/solr/solr-ref-guide/src/using-zookeeper-to-manage-configuration-files.adoc
@@ -93,4 +93,4 @@ If you for example would like to keep your `solr.xml` in ZooKeeper to avoid havi
bin/solr zk cp file:local/file/path/to/solr.xml zk:/solr.xml -z localhost:2181
----
-NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-s-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.
+NOTE: If you have defined `ZK_HOST` in `solr.in.sh`/`solr.in.cmd` (see <<setting-up-an-external-zookeeper-ensemble#updating-solr-include-files,instructions>>) you can omit `-z <zk host string>` from the above command.