docs: Split README content into more files
Many Gerrit plugin admins/devs expect to find most docs in
src/main/resources/Documentation/ but we also want to have a useful
top-level README. Support both cases by moving some README content into
individual Documentation/ files and linking to it from the README and
other Documentation/ files.
Also fix typos in several of the docs.
Change-Id: I8b218d06758dbd19d04bce0c7a6d4ea4cbd6bc89
diff --git a/README.md b/README.md
index 6565f33..b231e37 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
Indexing backend libModule for [Gerrit Code Review](https://gerritcodereview.com)
based on [ElasticSearch](https://www.elastic.co/elasticsearch/).
-This module was original part of Gerrit core and then extracted into a separate
+This module was originally part of Gerrit core and then extracted into a separate
component from v3.5.0-rc3 as part of [Change-Id: Ib7b5167ce](https://gerrit-review.googlesource.com/c/gerrit/+/323676).
## How to build
@@ -13,32 +13,13 @@
## Setup
-* Install index-elasticsearch module
+See the [setup instructions](src/main/resources/Documentation/setup.md) for how to install the
+index-elasticsearch module.
-Install the index-elasticsearch.jar into the `$GERRIT_SITE/lib` directory.
-
-Add the index-elasticsearch module to `$GERRIT_SITE/etc/gerrit.config` as follows:
-
-```ini
-[gerrit]
- installIndexModule = com.google.gerrit.elasticsearch.ElasticIndexModule
-```
-
-When installing the module on Gerrit replicas, use following example:
-
-```ini
-[gerrit]
- installIndexModule = com.google.gerrit.elasticsearch.ReplicaElasticIndexModule
-```
-
-For further information and supported options, refer to [config](src/main/resources/Documentation/config.md)
+For further information and supported options, refer to the [config](src/main/resources/Documentation/config.md)
documentation.
## Integration test
-Gerrit acceptance tests allow the execution with an alternate implementation of
-the indexing backend using the `GERRIT_INDEX_MODULE` environment variable.
-
-```sh
-bazel test --test_env=GERRIT_INDEX_MODULE=com.google.gerrit.elasticsearch.ElasticIndexModule //...
-```
+This libModule runs tests like a Gerrit in-tree plugin, using Bazelisk. See the
+[test instructions](src/main/resources/Documentation/build.md#Integration-test) for more details.
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
new file mode 100644
index 0000000..59fe0a3
--- /dev/null
+++ b/src/main/resources/Documentation/about.md
@@ -0,0 +1,7 @@
+# Index backend for Gerrit, based on ElasticSearch
+
+Indexing backend libModule for [Gerrit Code Review](https://gerritcodereview.com)
+based on [ElasticSearch](https://www.elastic.co/elasticsearch/).
+
+This module was originally part of Gerrit core and then extracted into a separate
+component from v3.5.0-rc3 as part of [Change-Id: Ib7b5167ce](https://gerrit-review.googlesource.com/c/gerrit/+/323676).
diff --git a/src/main/resources/Documentation/build.md b/src/main/resources/Documentation/build.md
index 1720f52..590c96d 100644
--- a/src/main/resources/Documentation/build.md
+++ b/src/main/resources/Documentation/build.md
@@ -4,9 +4,9 @@
## Build in Gerrit tree
-Create a symbolic link of the repsotiory source to the Gerrit source
-tree /plugins/index-elasticsearch directory, and the external_plugin_deps.bzl
-dependencies linked to /plugins/external_plugin_deps.bzl.
+Create a symbolic link of the repository source to the Gerrit source
+tree plugins/index-elasticsearch directory, and the external_plugin_deps.bzl
+dependencies linked to plugins/external_plugin_deps.bzl.
Example:
@@ -18,7 +18,7 @@
ln -sf ../../external_plugin_deps.bzl .
```
-From the Gerrit source tree issue the command `bazelsk build plugins/index-elasticsearch`.
+From the Gerrit source tree issue the command `bazelisk build plugins/index-elasticsearch`.
Example:
@@ -26,16 +26,29 @@
bazelisk build plugins/index-elasticsearch
```
-The libModule jar file is created under `basel-bin/plugins/index-elasticsearch/index-elasticsearch.jar`
+The libModule jar file is created under `bazel-bin/plugins/index-elasticsearch/index-elasticsearch.jar`
-To execute the tests run `bazelisk test plugins/index-elasticsearch/...` from the Gerrit source tree.
+## Integration test
-Example:
+There are two different ways to run tests for this module. You can either run only the tests
+provided by the module or you can run all Gerrit core acceptance tests with the indexing backend set
+to this module.
+
+To run only the tests provided by this plugin:
```sh
bazelisk test plugins/index-elasticsearch/...
```
+Gerrit acceptance tests allow the execution with an alternate implementation of
+the indexing backend using the `GERRIT_INDEX_MODULE` environment variable.
+
+```sh
+bazelisk test --test_env=GERRIT_INDEX_MODULE=com.google.gerrit.elasticsearch.ElasticIndexModule //...
+```
+
+## IDE setup
+
This project can be imported into the Eclipse IDE.
Add the plugin name to the `CUSTOM_PLUGINS` and to the
`CUSTOM_PLUGINS_TEST_DEPS` set in Gerrit core in
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index 4122c08..ad5d5d0 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -91,3 +91,7 @@
Password used to connect to Elasticsearch.
Not set by default.
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
diff --git a/src/main/resources/Documentation/setup.md b/src/main/resources/Documentation/setup.md
new file mode 100644
index 0000000..7877b29
--- /dev/null
+++ b/src/main/resources/Documentation/setup.md
@@ -0,0 +1,26 @@
+# Setup
+
+* Install index-elasticsearch module
+
+Install the index-elasticsearch.jar into the `$GERRIT_SITE/lib` directory.
+
+Add the index-elasticsearch module to `$GERRIT_SITE/etc/gerrit.config` as follows:
+
+```ini
+[gerrit]
+ installIndexModule = com.google.gerrit.elasticsearch.ElasticIndexModule
+```
+
+When installing the module on Gerrit replicas, use following example:
+
+```ini
+[gerrit]
+ installIndexModule = com.google.gerrit.elasticsearch.ReplicaElasticIndexModule
+```
+
+For further information and supported options, refer to [config](config.html)
+documentation.
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
