[DOCS] Reformat shrink index API docs (#46711) (#47587)

Author: jrodewig

docs/reference/indices/shrink-index.asciidoc

@@ -4,40 +4,36 @@
 <titleabbrev>Shrink index</titleabbrev>
 ++++
 
-The shrink index API allows you to shrink an existing index into a new index
-with fewer primary shards. The requested number of primary shards in the target index
-must be a factor of the number of shards in the source index. For example an index with
-`8` primary shards can be shrunk into `4`, `2` or `1` primary shards or an index
-with `15` primary shards can be shrunk into `5`, `3` or `1`. If the number
-of shards in the index is a prime number it can only be shrunk into a single
-primary shard. Before shrinking, a (primary or replica) copy of every shard
-in the index must be present on the same node.
+Shrinks an existing index into a new index with fewer primary shards.
 
-Shrinking works as follows:
 
-* First, it creates a new target index with the same definition as the source
-  index, but with a smaller number of primary shards.
+[source,console]
+----
+POST /twitter/_shrink/shrunk-twitter-index
+----
+// TEST[s/^/PUT twitter\n{"settings":{"index.number_of_shards":2,"blocks.write":true}}\n/]
 
-* Then it hard-links segments from the source index into the target index. (If
-  the file system doesn't support hard-linking, then all segments are copied
-  into the new index, which is a much more time consuming process. Also if using 
-  multiple data paths, shards on different data paths require a full copy of 
-  segment files if they are not on the same disk since hardlinks don’t work across
-  disks)
 
-* Finally, it recovers the target index as though it were a closed index which
-  had just been re-opened.
+[[shrink-index-api-request]]
+==== {api-request-title}
+
+`POST /<index>/_shrink/<target-index>`
+
+`PUT /<index>/_shrink/<target-index>`
+
 
-[float]
-==== Preparing an index for shrinking
+[[shrink-index-api-prereqs]]
+==== {api-prereq-title}
 
-In order to shrink an index, the index must be marked as read-only, and a
-(primary or replica) copy of every shard in the index must be relocated to the
-same node and have <<cluster-health,health>> `green`.
+Before you can shrink an index:
 
-These two conditions can be achieved with the following request:
+* The index must be read-only.
+* A copy of every shard in the index must reside on the same node.
+* The <<cluster-health, cluster health>> status must be green.
 
-[source,js]
+These three conditions can be achieved with the following request:
+
+[source,console]
 --------------------------------------------------
 PUT /my_source_index/_settings
 {
@@ -47,7 +43,6 @@ PUT /my_source_index/_settings
   }
 }
 --------------------------------------------------
-// CONSOLE
 // TEST[s/^/PUT my_source_index\n{"settings":{"index.number_of_shards":2}}\n/]
 <1> Forces the relocation of a copy of each shard to the node with name
     `shrink_node_name`.  See <<shard-allocation-filtering>> for more options.
@@ -60,23 +55,54 @@ with the <<cat-recovery,`_cat recovery` API>>, or the <<cluster-health,
 `cluster health` API>> can be used to wait until all shards have relocated
 with the `wait_for_no_relocating_shards` parameter.
 
-[float]
-==== Shrinking an index
+
+[[shrink-index-api-desc]]
+==== {api-description-title}
+
+The shrink index API allows you to shrink an existing index into a new index
+with fewer primary shards. The requested number of primary shards in the target index
+must be a factor of the number of shards in the source index. For example an index with
+`8` primary shards can be shrunk into `4`, `2` or `1` primary shards or an index
+with `15` primary shards can be shrunk into `5`, `3` or `1`. If the number
+of shards in the index is a prime number it can only be shrunk into a single
+primary shard. Before shrinking, a (primary or replica) copy of every shard
+in the index must be present on the same node.
+
+[[how-shrink-works]]
+===== How shrinking works
+
+A shrink operation:
+
+. Creates a new target index with the same definition as the source
+  index, but with a smaller number of primary shards.
+
+. Hard-links segments from the source index into the target index. (If
+  the file system doesn't support hard-linking, then all segments are copied
+  into the new index, which is a much more time consuming process. Also if using 
+  multiple data paths, shards on different data paths require a full copy of 
+  segment files if they are not on the same disk since hardlinks don’t work across
+  disks)
+
+. Recovers the target index as though it were a closed index which
+  had just been re-opened.
+
+
+[[_shrinking_an_index]]
+===== Shrink an index
 
 To shrink `my_source_index` into a new index called `my_target_index`, issue
 the following request:
 
-[source,js]
+[source,console]
 --------------------------------------------------
-POST my_source_index/_shrink/my_target_index
+POST /my_source_index/_shrink/my_target_index
 {
   "settings": {
     "index.routing.allocation.require._name": null, <1>
     "index.blocks.write": null <2>
   }
 }
 --------------------------------------------------
-// CONSOLE
 // TEST[continued]
 
 <1> Clear the allocation requirement copied from the source index.
@@ -110,9 +136,9 @@ Indices can only be shrunk if they satisfy the following requirements:
 The `_shrink` API is similar to the <<indices-create-index, `create index` API>>
 and accepts `settings` and `aliases` parameters for the target index:
 
-[source,js]
+[source,console]
 --------------------------------------------------
-POST my_source_index/_shrink/my_target_index
+POST /my_source_index/_shrink/my_target_index
 {
   "settings": {
     "index.number_of_replicas": 1,
@@ -124,7 +150,6 @@ POST my_source_index/_shrink/my_target_index
   }
 }
 --------------------------------------------------
-// CONSOLE
 // TEST[s/^/PUT my_source_index\n{"settings": {"index.number_of_shards":5,"index.blocks.write": true}}\n/]
 
 <1> The number of shards in the target index. This must be a factor of the
@@ -136,8 +161,9 @@ POST my_source_index/_shrink/my_target_index
 
 NOTE: Mappings may not be specified in the `_shrink` request.
 
-[float]
-==== Monitoring the shrink process
+
+[[monitor-shrink]]
+===== Monitor the shrink process
 
 The shrink process can be monitored with the <<cat-recovery,`_cat recovery`
 API>>, or the <<cluster-health, `cluster health` API>> can be used to wait
@@ -155,9 +181,35 @@ shrink process begins. When the shrink operation completes, the shard will
 become `active`. At that  point, Elasticsearch will try to allocate any
 replicas and may decide to relocate the primary shard to another node.
 
-[float]
-==== Wait For Active Shards
+
+[[shrink-wait-active-shards]]
+===== Wait for active shards
 
 Because the shrink operation creates a new index to shrink the shards to,
 the <<create-index-wait-for-active-shards,wait for active shards>> setting
 on index creation applies to the shrink index action as well.
+
+
+[[shrink-index-api-path-params]]
+==== {api-path-parms-title}
+
+`<index>`::
+(Required, string)
+Name of the source index to shrink.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index]
+
+[[shrink-index-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+
+[[shrink-index-api-request-body]]
+==== {api-request-body-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-aliases]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=target-index-settings]