From d08e7633f89663f3ba8881818ebcd08604e5657c Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Wed, 29 Jul 2020 10:53:50 -0400
Subject: [PATCH] [DOCS] Add `number_of_routing_shards` index setting to index
 modules (#60311) (#60400)

Changes:

* Adds the `number_of_routing_shards` index setting to index modules docs.
* Updates the split API docs to mention that `number_of_routing_shards`
is a static setting.
---
 docs/reference/index-modules.asciidoc       | 19 ++++++++++++
 docs/reference/indices/split-index.asciidoc | 34 ++++++++++++++++++---
 2 files changed, 48 insertions(+), 5 deletions(-)

diff --git a/docs/reference/index-modules.asciidoc b/docs/reference/index-modules.asciidoc
index 73a70122d08..e833ab333fd 100644
--- a/docs/reference/index-modules.asciidoc
+++ b/docs/reference/index-modules.asciidoc
@@ -46,6 +46,25 @@ NOTE: The number of shards are limited to `1024` per index. This limitation is a
 
 // end::index-number-of-shards-tag[]
 
+[[index-number-of-routing-shards]]
+`index.number_of_routing_shards`::
++
+====
+Number of routing shards used to <<indices-split-index,split>> an index.
+
+For example, a 5 shard index with `number_of_routing_shards` set to `30` (`5 x
+2 x 3`) could be split by a factor of `2` or `3`.  In other words, it could be
+split as follows:
+
+* `5` -> `10` -> `30`  (split by 2, then by 3)
+* `5` -> `15` -> `30` (split by 3, then by 2)
+* `5` -> `30` (split by 6)
+
+This setting's default value depends on the number of primary shards in the
+index. The default is designed to allow you to split by factors of 2 up
+to a maximum of 1024 shards.
+====
+
 `index.shard.check_on_startup`::
 
 Whether or not shards should be checked for corruption before opening. When
diff --git a/docs/reference/indices/split-index.asciidoc b/docs/reference/indices/split-index.asciidoc
index 1d8d8ef6e73..12b2f80aa7f 100644
--- a/docs/reference/indices/split-index.asciidoc
+++ b/docs/reference/indices/split-index.asciidoc
@@ -76,11 +76,35 @@ factor of `2` or `3`.  In other words, it could be split as follows:
 * `5` -> `15` -> `30` (split by 3, then by 2)
 * `5` -> `30` (split by 6)
 
-While you can set the `index.number_of_routing_shards` setting explicitly at
-index creation time, the default value depends upon the number of primary
-shards in the original index.  The default is designed to allow you to split
-by factors of 2 up to a maximum of 1024 shards.  However, the original number
-of primary shards must taken into account.  For instance, an index created
+`index.number_of_routing_shards` is a <<index-modules-settings,static index
+setting>>. You can only set `index.number_of_routing_shards` at index creation
+time or on a <<indices-open-close,closed index>>.
+
+.*Index creation example*
+[%collapsible]
+====
+The following <<indices-create-index,create index API>> creates the
+`my-index-000001` index with an `index.number_of_routing_shards` setting of `30`.
+
+[source,console]
+----
+PUT /my-index-000001
+{
+  "settings": {
+    "index": {
+      "number_of_routing_shards": 30
+    }
+  }
+}
+----
+// TEST[continued]
+====
+
+The `index.number_of_routing_shards` setting's default value depends 
+on the number of primary shards in the original index.
+The default is designed to allow you to split
+by factors of 2 up to a maximum of 1024 shards. However, the original number
+of primary shards must taken into account. For instance, an index created
 with 5 primary shards could be split into 10, 20, 40, 80, 160, 320, or a
 maximum of 640 shards (with a single split action or multiple split actions).