[DOCS] Reformat doc delete API reference. (#45422)

* [DOCS] Reformat doc delete API reference.

docs/reference/docs/delete.asciidoc

@@ -1,53 +1,35 @@
 [[docs-delete]]
 === Delete API
+++++
+<titleabbrev>Delete</titleabbrev>
+++++
 
-The delete API allows to delete a JSON document from a specific
-index based on its id. The following example deletes the JSON document
-from an index called `twitter` with ID `1`:
+Removes a JSON document from the specified index.
 
-[source,js]
---------------------------------------------------
-DELETE /twitter/_doc/1
---------------------------------------------------
-// CONSOLE
-// TEST[setup:twitter]
+[[docs-delete-api-request]]
+==== {api-request-title}
 
-The result of the above delete operation is:
+`DELETE /<index>/_doc/<_id>`
 
-[source,js]
---------------------------------------------------
-{
-    "_shards" : {
-        "total" : 2,
-        "failed" : 0,
-        "successful" : 2
-    },
-    "_index" : "twitter",
-    "_type" : "_doc",
-    "_id" : "1",
-    "_version" : 2,
-    "_primary_term": 1,
-    "_seq_no": 5,
-    "result": "deleted"
-}
---------------------------------------------------
-// TESTRESPONSE[s/"successful" : 2/"successful" : 1/]
-// TESTRESPONSE[s/"_primary_term" : 1/"_primary_term" : $body._primary_term/]
-// TESTRESPONSE[s/"_seq_no" : 5/"_seq_no" : $body._seq_no/]
+[[docs-delete-api-desc]]
+==== {api-description-title}
+
+You use DELETE to remove a document from an index. You must specify the
+index name and document ID.
 
 [float]
 [[optimistic-concurrency-control-delete]]
-==== Optimistic concurrency control
+===== Optimistic concurrency control
 
 Delete operations can be made conditional and only be performed if the last
-modification to the document was assigned the sequence number and primary 
+modification to the document was assigned the sequence number and primary
 term specified by the `if_seq_no` and `if_primary_term` parameters. If a
 mismatch is detected, the operation will result in a `VersionConflictException`
-and a status code of 409. See <<optimistic-concurrency-control>> for more details. 
+and a status code of 409. See <<optimistic-concurrency-control>> for more details.
 
 [float]
 [[delete-versioning]]
-==== Versioning
+===== Versioning
 
 Each document indexed is versioned. When deleting a document, the `version` can
 be specified to make sure the relevant document we are trying to delete is
@@ -60,11 +42,17 @@ determined by the `index.gc_deletes` index setting and defaults to 60 seconds.
 
 [float]
 [[delete-routing]]
-==== Routing
+===== Routing
+
+If routing is used during indexing, the routing value also needs to be
+specified to delete a document.
+
+If the `_routing` mapping is set to `required` and no routing value is
+specified, the delete API throws a `RoutingMissingException` and rejects
+the request.
+
+For example:
 
-When indexing using the ability to control the routing, in order to
-delete a document, the routing value should also be provided. For
-example:
 
 ////
 Example to delete with routing
@@ -87,26 +75,21 @@ DELETE /twitter/_doc/1?routing=kimchy
 // CONSOLE
 // TEST[continued]
 
-The above will delete a tweet with id `1`, but will be routed based on the
-user. Note that issuing a delete without the correct routing will cause the
-document to not be deleted.
-
-When the `_routing` mapping is set as `required` and no routing value is
-specified, the delete API will throw a `RoutingMissingException` and reject
-the request.
+This request deletes the tweet with id `1`, but it is routed based on the
+user. The document is not deleted if the correct routing is not specified.
 
 [float]
 [[delete-index-creation]]
-==== Automatic index creation
+===== Automatic index creation
 
 If an <<docs-index_,external versioning variant>> is used,
-the delete operation automatically creates an index if it has not been
-created before (check out the <<indices-create-index,create index API>>
-for manually creating an index).
+the delete operation automatically creates the specified index if it does not
+exist. For information about manually creating indices, see
+<<indices-create-index,create index API>>.
 
 [float]
 [[delete-distributed]]
-==== Distributed
+===== Distributed
 
 The delete operation gets hashed into a specific shard id. It then gets
 redirected into the primary shard within that id group, and replicated
@@ -114,7 +97,7 @@ redirected into the primary shard within that id group, and replicated
 
 [float]
 [[delete-wait-for-active-shards]]
-==== Wait For Active Shards
+===== Wait for active shards
 
 When making delete requests, you can set the `wait_for_active_shards`
 parameter to require a minimum number of shard copies to be active
@@ -124,15 +107,14 @@ example.
 
 [float]
 [[delete-refresh]]
-==== Refresh
+===== Refresh
 
 Control when the changes made by this request are visible to search. See
 <<docs-refresh>>.
 
-
 [float]
 [[delete-timeout]]
-==== Timeout
+===== Timeout
 
 The primary shard assigned to perform the delete operation might not be
 available when the delete operation is executed. Some reasons for this
@@ -149,3 +131,68 @@ DELETE /twitter/_doc/1?timeout=5m
 --------------------------------------------------
 // CONSOLE
 // TEST[setup:twitter]
+
+[[docs-delete-api-path-params]]
+==== {api-path-parms-title}
+
+`<index>`::
+(Required, string) Name of the target index.
+
+`<_id>`::
+(Required, string) Unique identifier for the document.
+
+[[docs-delete-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-seq-no]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-primary-term]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-pipeline]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-refresh]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-routing]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeout]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-version-type]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=doc-wait-for-active-shards]
+
+[[docs-delete-api-example]]
+==== {api-examples-title}
+
+Delete the JSON document `1` from the `twitter` index:
+
+[source,js]
+--------------------------------------------------
+DELETE /twitter/_doc/1
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:twitter]
+
+The API returns the following result:
+
+[source,js]
+--------------------------------------------------
+{
+    "_shards" : {
+        "total" : 2,
+        "failed" : 0,
+        "successful" : 2
+    },
+    "_index" : "twitter",
+    "_type" : "_doc",
+    "_id" : "1",
+    "_version" : 2,
+    "_primary_term": 1,
+    "_seq_no": 5,
+    "result": "deleted"
+}
+--------------------------------------------------
+// TESTRESPONSE[s/"successful" : 2/"successful" : 1/]
+// TESTRESPONSE[s/"_primary_term" : 1/"_primary_term" : $body._primary_term/]
+// TESTRESPONSE[s/"_seq_no" : 5/"_seq_no" : $body._seq_no/]

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

@@ -123,10 +123,12 @@ end::doc-wait-for-active-shards[]
 
 tag::timeoutparms[]
 
+tag::timeout[]
 `timeout`::
 (Optional, <<time-units, time units>>) Specifies the period of time to wait for
 a response. If no response is received before the timeout expires, the request
 fails and returns an error. Defaults to `30s`.
+end::timeout[]
 
 tag::master-timeout[]
 `master_timeout`::