Consolify snapshot documentation (#23189)

This commit brings the snapshot documentation in conformity
with the CONSOLE format, and fixes the docs so that the documentation
tests can be run against them.

docs/build.gradle

@@ -121,7 +121,7 @@ buildRestTests.expectedUnconvertedCandidates = [
   'reference/mapping/types/percolator.asciidoc',
   'reference/modules/scripting/security.asciidoc',
   'reference/modules/scripting/using.asciidoc',
-  'reference/modules/cross-cluster-search.asciidoc', // this is hart to test since we need 2 clusters -- maybe we can trick it into referencing itself...
+  'reference/modules/cross-cluster-search.asciidoc', // this is hard to test since we need 2 clusters -- maybe we can trick it into referencing itself...
   'reference/query-dsl/exists-query.asciidoc',
   'reference/query-dsl/function-score-query.asciidoc',
   'reference/query-dsl/geo-shape-query.asciidoc',
@@ -154,7 +154,7 @@ integTest {
   }
 }
 
-// Build the cluser with all plugins
+// Build the cluster with all plugins
 
 project.rootProject.subprojects.findAll { it.parent.path == ':plugins' }.each { subproj ->
   /* Skip repositories. We just aren't going to be able to test them so it
@@ -176,8 +176,6 @@ buildRestTests.docs = fileTree(projectDir) {
   exclude 'build.gradle'
   // That is where the snippets go, not where they come from!
   exclude 'build'
-  // This file simply doesn't pass yet. We should figure out how to fix it.
-  exclude 'reference/modules/snapshots.asciidoc'
 }
 
 Closure setupTwitter = { String name, int count ->

docs/reference/modules/snapshots.asciidoc

@@ -28,10 +28,12 @@ PUT /_snapshot/my_backup
 {
   "type": "fs",
   "settings": {
-        ... repository specific settings ...
+    "location": "my_backup_location"
   }
 }
 -----------------------------------
+// CONSOLE
+// TESTSETUP
 
 Once a repository is registered, its information can be obtained using the following command:
 
@@ -49,12 +51,12 @@ which returns:
   "my_backup": {
     "type": "fs",
     "settings": {
-      "compress": true,
+      "location": "my_backup_location"
-      "location": "/mount/backups/my_backup"
     }
   }
 }
 -----------------------------------
+// TESTRESPONSE
 
 Information about multiple repositories can be fetched in one go by using a comma-delimited list of repository names.
 Star wildcards are supported as well. For example, information about repositories that start with `repo` or that contain `backup`
@@ -64,6 +66,7 @@ can be obtained using the following command:
 -----------------------------------
 GET /_snapshot/repo*,*backup*
 -----------------------------------
+// CONSOLE
 
 If a repository name is not specified, or `_all` is used as repository name Elasticsearch will return information about
 all repositories currently registered in the cluster:
@@ -72,6 +75,7 @@ all repositories currently registered in the cluster:
 -----------------------------------
 GET /_snapshot
 -----------------------------------
+// CONSOLE
 
 or
 
@@ -79,6 +83,7 @@ or
 -----------------------------------
 GET /_snapshot/_all
 -----------------------------------
+// CONSOLE
 
 [float]
 ===== Shared File System Repository
@@ -109,28 +114,34 @@ the name `my_backup`:
 
 [source,js]
 -----------------------------------
-$ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
+PUT /_snapshot/my_fs_backup
+{
     "type": "fs",
     "settings": {
-        "location": "/mount/backups/my_backup",
+        "location": "/mount/backups/my_fs_backup_location",
         "compress": true
     }
-}'
+}
 -----------------------------------
+// CONSOLE
+// TEST[skip:no access to absolute path]
 
 If the repository location is specified as a relative path this path will be resolved against the first path specified
 in `path.repo`:
 
 [source,js]
 -----------------------------------
-$ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
+PUT /_snapshot/my_fs_backup
+{
     "type": "fs",
     "settings": {
-        "location": "my_backup",
+        "location": "my_fs_backup_location",
         "compress": true
     }
-}'
+}
 -----------------------------------
+// CONSOLE
+// TEST[continued]
 
 The following settings are supported:
 
@@ -183,24 +194,25 @@ verification when registering or updating a repository:
 
 [source,js]
 -----------------------------------
-PUT /_snapshot/s3_repository?verify=false
+PUT /_snapshot/my_unverified_backup?verify=false
 {
-  "type": "s3",
+  "type": "fs",
   "settings": {
-    "bucket": "my_s3_bucket",
+    "location": "my_unverified_backup_location"
-    "region": "eu-west-1"
   }
 }
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 The verification process can also be executed manually by running the following command:
 
 [source,js]
 -----------------------------------
-POST /_snapshot/s3_repository/_verify
+POST /_snapshot/my_unverified_backup/_verify
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 It returns a list of nodes where repository was successfully verified or an error message if verification process failed.
 
@@ -216,6 +228,7 @@ command:
 PUT /_snapshot/my_backup/snapshot_1?wait_for_completion=true
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 The `wait_for_completion` parameter specifies whether or not the request should return immediately after snapshot
 initialization (default) or wait for snapshot completion. During snapshot initialization, information about all
@@ -227,7 +240,7 @@ specifying the list of indices in the body of the snapshot request.
 
 [source,js]
 -----------------------------------
-PUT /_snapshot/my_backup/snapshot_1
+PUT /_snapshot/my_backup/snapshot_2?wait_for_completion=true
 {
   "indices": "index_1,index_2",
   "ignore_unavailable": true,
@@ -235,6 +248,7 @@ PUT /_snapshot/my_backup/snapshot_1
 }
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 The list of indices that should be included into the snapshot can be specified using the `indices` parameter that
 supports <<search-multi-index-type,multi index syntax>>. The snapshot request also supports the
@@ -271,6 +285,7 @@ Once a snapshot is created information about this snapshot can be obtained using
 GET /_snapshot/my_backup/snapshot_1
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 Similar as for repositories, information about multiple snapshots can be queried in one go, supporting wildcards as well:
 
@@ -279,6 +294,7 @@ Similar as for repositories, information about multiple snapshots can be queried
 GET /_snapshot/my_backup/snapshot_*,some_other_snapshot
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 All snapshots currently stored in the repository can be listed using the following command:
 
@@ -287,6 +303,7 @@ All snapshots currently stored in the repository can be listed using the followi
 GET /_snapshot/my_backup/_all
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 The command fails if some of the snapshots are unavailable. The boolean parameter `ignore_unavailable` can be used to
 return all snapshots that are currently available.
@@ -295,16 +312,19 @@ A currently running snapshot can be retrieved using the following command:
 
 [source,sh]
 -----------------------------------
-$ curl -XGET "localhost:9200/_snapshot/my_backup/_current"
+GET /_snapshot/my_backup/_current
 -----------------------------------
+// CONSOLE
+// TEST[continued]
 
 A snapshot can be deleted from the repository using the following command:
 
 [source,sh]
 -----------------------------------
-DELETE /_snapshot/my_backup/snapshot_1
+DELETE /_snapshot/my_backup/snapshot_2
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 When a snapshot is deleted from a repository, Elasticsearch deletes all files that are associated with the deleted
 snapshot and not used by any other snapshots. If the deleted snapshot operation is executed while the snapshot is being
@@ -316,9 +336,10 @@ A repository can be deleted using the following command:
 
 [source,sh]
 -----------------------------------
-DELETE /_snapshot/my_backup
+DELETE /_snapshot/my_fs_backup
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 When a repository is deleted, Elasticsearch only removes the reference to the location where the repository is storing
 the snapshots. The snapshots themselves are left untouched and in place.
@@ -333,6 +354,7 @@ A snapshot can be restored using the following command:
 POST /_snapshot/my_backup/snapshot_1/_restore
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 By default, all indices in the snapshot are restored, and the cluster state is
 *not* restored. It's possible to select indices that should be restored as well
@@ -358,6 +380,7 @@ POST /_snapshot/my_backup/snapshot_1/_restore
 }
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 The restore operation can be performed on a functioning cluster. However, an
 existing index can be only restored if it's <<indices-open-close,closed>> and
@@ -398,6 +421,7 @@ POST /_snapshot/my_backup/snapshot_1/_restore
 }
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 Please note, that some settings such as `index.number_of_shards` cannot be changed during restore operation.
 
@@ -432,6 +456,7 @@ A list of currently running snapshots with their detailed status information can
 GET /_snapshot/_status
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 In this format, the command will return information about all currently running snapshots. By specifying a repository name, it's possible
 to limit the results to a particular repository:
@@ -441,6 +466,7 @@ to limit the results to a particular repository:
 GET /_snapshot/my_backup/_status
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 If both repository name and snapshot id are specified, this command will return detailed status information for the given snapshot even
 if it's not currently running:
@@ -450,6 +476,7 @@ if it's not currently running:
 GET /_snapshot/my_backup/snapshot_1/_status
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 Multiple ids are also supported:
 
@@ -458,6 +485,7 @@ Multiple ids are also supported:
 GET /_snapshot/my_backup/snapshot_1,snapshot_2/_status
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 [float]
 === Monitoring snapshot/restore progress
@@ -473,6 +501,7 @@ The snapshot operation can be also monitored by periodic calls to the snapshot i
 GET /_snapshot/my_backup/snapshot_1
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 Please note that snapshot info operation uses the same resources and thread pool as the snapshot operation. So,
 executing a snapshot info operation while large shards are being snapshotted can cause the snapshot info operation to wait
@@ -485,6 +514,7 @@ To get more immediate and complete information about snapshots the snapshot stat
 GET /_snapshot/my_backup/snapshot_1/_status
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 While snapshot info method returns only basic information about the snapshot in progress, the snapshot status returns
 complete breakdown of the current state for each shard participating in the snapshot.
@@ -514,6 +544,7 @@ that snapshot before deleting the snapshot data from the repository.
 DELETE /_snapshot/my_backup/snapshot_1
 -----------------------------------
 // CONSOLE
+// TEST[continued]
 
 The restore operation uses the standard shard recovery mechanism. Therefore, any currently running restore operation can
 be canceled by deleting indices that are being restored. Please note that data for all deleted indices will be removed