[DOCS] Reformats cat indices API (#45239)

docs/reference/cat/indices.asciidoc

@@ -1,9 +1,86 @@
 [[cat-indices]]
 === cat indices
 
-The `indices` command provides a cross-section of each index.  This
+Returns high-level information about indices in a cluster.
-information *spans nodes*. For example:
 
+
+[[cat-indices-api-request]]
+==== {api-request-title}
+
+`GET /_cat/indices/{index}`
+
+
+[[cat-indices-api-desc]]
+==== {api-description-title}
+
+Use the cat indices API to get the following information for each index in a
+cluster:
+
+* Shard count
+* Document count
+* Deleted document count
+* Primary store size
+* Total store size of all shards, including shard replicas
+
+These metrics are retrieved directly from
+https://lucene.apache.org/core/[Lucene], which {es} uses internally to power
+indexing and search. As a result, all document counts include hidden
+<<nested,nested>> documents.
+
+To get an accurate count of {es} documents, use the <<cat-count,cat count>> or
+<<search-count,count>> APIs.
+
+
+[[cat-indices-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
+
+
+[[cat-indices-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
+`health`::
++
+--
+(Optional, string) Health status used to limit returned indices. Valid values
+are:
+
+* `green`
+* `yellow`
+* `red`
+
+By default, the response includes indices of any health status.
+--
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout]
+
+[[pri-flag]]
+`pri` (primary shards)::
+(Optional, boolean) If `true`, the response only includes information from
+primary shards. Defaults to `false`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+
+[[cat-indices-api-example]]
+==== {api-examples-title}
+
+[[examples]]
 [source,js]
 --------------------------------------------------
 GET /_cat/indices/twi*?v&s=index
@@ -12,7 +89,7 @@ GET /_cat/indices/twi*?v&s=index
 // TEST[setup:huge_twitter]
 // TEST[s/^/PUT twitter2\n{"settings": {"number_of_replicas": 0}}\n/]
 
-Might respond with:
+The API returns the following response:
 
 [source,txt]
 --------------------------------------------------
@@ -21,105 +98,4 @@ yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0
 green  open   twitter2 nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
 --------------------------------------------------
 // TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
+// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
-
-We can tell quickly how many shards make up an index, the number of
-docs, deleted docs, primary store size, and total store size (all shards including replicas).
-All these exposed metrics come directly from Lucene APIs.
-
-*Notes:*
-
-1. As the number of documents and deleted documents shown in this are at the lucene level,
-it includes all the hidden documents (e.g. from nested documents) as well.
-
-2. To get actual count of documents at the Elasticsearch level, the recommended way
-is to use either the <<cat-count>> or the <<search-count>>
-
-[float]
-[[pri-flag]]
-==== Primaries
-
-The index stats by default will show them for all of an index's
-shards, including replicas.  A `pri` flag can be supplied to enable
-the view of relevant stats in the context of only the primaries.
-
-[float]
-[[examples]]
-==== Examples
-
-Which indices are yellow?
-
-[source,js]
---------------------------------------------------
-GET /_cat/indices?v&health=yellow
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-Which looks like:
-
-[source,txt]
---------------------------------------------------
-health status index    uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
---------------------------------------------------
-// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ/.+/ non_json]
-
-Which index has the largest number of documents?
-
-[source,js]
---------------------------------------------------
-GET /_cat/indices?v&s=docs.count:desc
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-Which looks like:
-
-[source,txt]
---------------------------------------------------
-health status index    uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-yellow open   twitter  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb
-green  open   twitter2 nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b
---------------------------------------------------
-// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[s/u8FNjxh8Rfy_awN11oDKYQ|nYFWZEO7TUiOjLQXBaYJpA/.+/ non_json]
-
-How many merge operations have the shards for the `twitter` completed?
-
-[source,js]
---------------------------------------------------
-GET /_cat/indices/twitter?pri&v&h=health,index,pri,rep,docs.count,mt
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-Might look like:
-
-[source,txt]
---------------------------------------------------
-health index   pri rep docs.count mt pri.mt
-yellow twitter   1   1 1200       16     16
---------------------------------------------------
-// TESTRESPONSE[s/16/\\d+/ non_json]
-
-How much memory is used per index?
-
-[source,js]
---------------------------------------------------
-GET /_cat/indices?v&h=i,tm&s=tm:desc
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-Might look like:
-
-[source,txt]
---------------------------------------------------
-i         tm
-twitter   8.1gb
-twitter2  30.5kb
---------------------------------------------------
-// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/]
-// TESTRESPONSE[non_json]

docs/reference/rest-api/common-parms.asciidoc

@@ -22,10 +22,16 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header].
 Valid values include JSON, YAML, etc.
 end::http-format[]
 
+tag::include-unloaded-segments[]
+`include_unloaded_segments`::
+(Optional, boolean) If `true`, the response includes information from segments
+that are **not** loaded into memory. Defaults to `false`.
+end::include-unloaded-segments[]
+
 tag::index[]
 `{index}`::
-(Optional, string) Comma-separated list of index names used to limit returned
+(Optional, string) Comma-separated list or wildcard expression of index names
-information.
+used to limit the request.
 end::index[]
 
 tag::local[]