From 840b768760e7153450ba4ea7970c1ef58729814d Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Thu, 28 Jun 2018 10:47:19 -0400 Subject: [PATCH] Docs: Remove duplicate test setup The range docs had an introductory section that described how to set up and index *and* a test setup section in `docs/build.gradle` that duplicated that section. This is bad because these section can (and do) drift from one another. This change removes the setup in build.gradle and marks the introductor snippet with `// TESTSETUP` so it is used on all the snippets. --- docs/README.asciidoc | 11 +++++---- docs/build.gradle | 25 --------------------- docs/reference/mapping/types/range.asciidoc | 9 ++++---- 3 files changed, 12 insertions(+), 33 deletions(-) diff --git a/docs/README.asciidoc b/docs/README.asciidoc index 4b185c3e168e3..dc380a8c41d3e 100644 --- a/docs/README.asciidoc +++ b/docs/README.asciidoc @@ -8,8 +8,8 @@ CONSOLE" and "COPY AS CURL" in the documentation and are automatically tested by the command `gradle :docs:check`. To test just the docs from a single page, use e.g. `gradle :docs:check -Dtests.method=*rollover*`. -NOTE: If you have an elasticsearch-extra folder alongside your elasticsearch -folder, you must temporarily rename it when you are testing 6.3 or later branches. +NOTE: If you have an elasticsearch-extra folder alongside your elasticsearch +folder, you must temporarily rename it when you are testing 6.3 or later branches. By default each `// CONSOLE` snippet runs as its own isolated test. You can manipulate the test execution in the following ways: @@ -37,7 +37,8 @@ for its modifiers: reason why the test shouldn't be run. * `// TEST[setup:name]`: Run some setup code before running the snippet. This is useful for creating and populating indexes used in the snippet. The setup - code is defined in `docs/build.gradle`. + code is defined in `docs/build.gradle`. See `// TESTSETUP` below for a + similar feature. * `// TEST[warning:some warning]`: Expect the response to include a `Warning` header. If the response doesn't include a `Warning` header with the exact text then the test fails. If the response includes `Warning` headers that @@ -69,7 +70,9 @@ for its modifiers: a test that runs the setup snippet first. See the "painless" docs for a file that puts this to good use. This is fairly similar to `// TEST[setup:name]` but rather than the setup defined in `docs/build.gradle` the setup is defined - right in the documentation file. + right in the documentation file. In general, we should prefer `// TESTSETUP` + over `// TEST[setup:name]` because it makes it more clear what steps have to + be taken before the examples will work. In addition to the standard CONSOLE syntax these snippets can contain blocks of yaml surrounded by markers like this: diff --git a/docs/build.gradle b/docs/build.gradle index 7021a09d463f2..51c46935dc6cd 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -220,31 +220,6 @@ buildRestTests.doFirst { buildRestTests.setups['bank'].replace('#bank_data#', accounts) } -buildRestTests.setups['range_index'] = ''' - - do : - indices.create: - index: range_index - body: - settings: - number_of_shards: 2 - number_of_replicas: 1 - mappings: - _doc: - properties: - expected_attendees: - type: integer_range - time_frame: - type: date_range - format: yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis - - do: - bulk: - index: range_index - type: _doc - refresh: true - body: | - {"index":{"_id": 1}} - {"expected_attendees": {"gte": 10, "lte": 20}, "time_frame": {"gte": "2015-10-31 12:00:00", "lte": "2015-11-01"}}''' - // Used by index boost doc buildRestTests.setups['index_boost'] = ''' - do: diff --git a/docs/reference/mapping/types/range.asciidoc b/docs/reference/mapping/types/range.asciidoc index a7ab6346176cb..082d012a49058 100644 --- a/docs/reference/mapping/types/range.asciidoc +++ b/docs/reference/mapping/types/range.asciidoc @@ -18,6 +18,9 @@ Below is an example of configuring a mapping with various range fields followed -------------------------------------------------- PUT range_index { + "settings": { + "number_of_shards": 2 + }, "mappings": { "_doc": { "properties": { @@ -33,7 +36,7 @@ PUT range_index } } -PUT range_index/_doc/1 +PUT range_index/_doc/1?refresh { "expected_attendees" : { <2> "gte" : 10, @@ -46,6 +49,7 @@ PUT range_index/_doc/1 } -------------------------------------------------- //CONSOLE +// TESTSETUP <1> `date_range` types accept the same field parameters defined by the <> type. <2> Example indexing a meeting with 10 to 20 attendees. @@ -68,7 +72,6 @@ GET range_index/_search } -------------------------------------------------- // CONSOLE -// TEST[setup:range_index] The result produced by the above query. @@ -125,7 +128,6 @@ GET range_index/_search } -------------------------------------------------- // CONSOLE -// TEST[setup:range_index] <1> Range queries work the same as described in <>. <2> Range queries over range <> support a `relation` parameter which can be one of `WITHIN`, `CONTAINS`, @@ -191,7 +193,6 @@ PUT range_index/_doc/2 } -------------------------------------------------- // CONSOLE -// TEST[setup:range_index] [[range-params]] ==== Parameters for range fields