From 94ec6e6139c0d0af9775340ced3741c393296a77 Mon Sep 17 00:00:00 2001 From: spalger Date: Mon, 1 May 2017 16:29:24 -0700 Subject: [PATCH] define description overrides by version, like examples --- docs/_descriptions/search.asciidoc | 2 +- docs/_descriptions/search_0.90.asciidoc | 2 + docs/_descriptions/search_1.x.asciidoc | 4 ++ docs/_descriptions/search_2.x.asciidoc | 4 ++ docs/_examples/scroll.asciidoc | 12 ++--- ...oll_5.0+.asciidoc => scroll_<5.0.asciidoc} | 14 +++--- docs/api_methods.asciidoc | 2 +- docs/api_methods_0_90.asciidoc | 3 +- docs/api_methods_1_7.asciidoc | 3 +- docs/api_methods_2_4.asciidoc | 3 +- docs/api_methods_5_0.asciidoc | 2 +- docs/api_methods_5_1.asciidoc | 2 +- docs/api_methods_5_2.asciidoc | 2 +- package.json | 5 +- scripts/Version.js | 47 ++++++++++++++----- scripts/generate/js_api.js | 10 +++- scripts/generate/overrides.js | 29 ++++++++++-- scripts/generate/templates/api_methods.tmpl | 2 +- scripts/generate/templates/index.js | 12 ----- 19 files changed, 102 insertions(+), 58 deletions(-) create mode 100644 docs/_descriptions/search_0.90.asciidoc create mode 100644 docs/_descriptions/search_1.x.asciidoc create mode 100644 docs/_descriptions/search_2.x.asciidoc rename docs/_examples/{scroll_5.0+.asciidoc => scroll_<5.0.asciidoc} (63%) diff --git a/docs/_descriptions/search.asciidoc b/docs/_descriptions/search.asciidoc index 82e979173..b2cc6fda3 100644 --- a/docs/_descriptions/search.asciidoc +++ b/docs/_descriptions/search.asciidoc @@ -1,4 +1,4 @@ Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], https://github.com/sudo-suhas/elastic-builder[elastic-builder] or https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. diff --git a/docs/_descriptions/search_0.90.asciidoc b/docs/_descriptions/search_0.90.asciidoc new file mode 100644 index 000000000..fe71efceb --- /dev/null +++ b/docs/_descriptions/search_0.90.asciidoc @@ -0,0 +1,2 @@ +Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. + diff --git a/docs/_descriptions/search_1.x.asciidoc b/docs/_descriptions/search_1.x.asciidoc new file mode 100644 index 000000000..3f7e06e5e --- /dev/null +++ b/docs/_descriptions/search_1.x.asciidoc @@ -0,0 +1,4 @@ +Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. + +TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], and https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier. + diff --git a/docs/_descriptions/search_2.x.asciidoc b/docs/_descriptions/search_2.x.asciidoc new file mode 100644 index 000000000..6ac0400d6 --- /dev/null +++ b/docs/_descriptions/search_2.x.asciidoc @@ -0,0 +1,4 @@ +Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. + +TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/sudo-suhas/elastic-builder[elastic-builder], and https://github.com/holidayextras/esq[esq] can be used to make building query bodies easier. + diff --git a/docs/_examples/scroll.asciidoc b/docs/_examples/scroll.asciidoc index ef169e650..02e8269db 100644 --- a/docs/_examples/scroll.asciidoc +++ b/docs/_examples/scroll.asciidoc @@ -6,19 +6,17 @@ var allTitles = []; // first we do a search, and specify a scroll timeout client.search({ index: 'myindex', - // Set to 30 seconds because we are calling right back - scroll: '30s', - search_type: 'scan', - fields: ['title'], + scroll: '30s', // keep the search results "scrollable" for 30 seconds + source: ['title'], // filter the source to only include the title field q: 'title:test' }, function getMoreUntilDone(error, response) { // collect the title from each response response.hits.hits.forEach(function (hit) { - allTitles.push(hit.fields.title); + allTitles.push(hit._source.title); }); - if (response.hits.total !== allTitles.length) { - // now we can call scroll over and over + if (response.hits.total > allTitles.length) { + // ask elasticsearch for the next set of hits from this search client.scroll({ scrollId: response._scroll_id, scroll: '30s' diff --git a/docs/_examples/scroll_5.0+.asciidoc b/docs/_examples/scroll_<5.0.asciidoc similarity index 63% rename from docs/_examples/scroll_5.0+.asciidoc rename to docs/_examples/scroll_<5.0.asciidoc index 02e8269db..36fcfa923 100644 --- a/docs/_examples/scroll_5.0+.asciidoc +++ b/docs/_examples/scroll_<5.0.asciidoc @@ -6,17 +6,19 @@ var allTitles = []; // first we do a search, and specify a scroll timeout client.search({ index: 'myindex', - scroll: '30s', // keep the search results "scrollable" for 30 seconds - source: ['title'], // filter the source to only include the title field + // Set to 30 seconds because we are calling right back + scroll: '30s', + search_type: 'scan', + fields: ['title'], q: 'title:test' }, function getMoreUntilDone(error, response) { // collect the title from each response response.hits.hits.forEach(function (hit) { - allTitles.push(hit._source.title); + allTitles.push(hit.fields.title); }); - if (response.hits.total > allTitles.length) { - // ask elasticsearch for the next set of hits from this search + if (response.hits.total !== allTitles.length) { + // now we can call scroll over and over client.scroll({ scrollId: response._scroll_id, scroll: '30s' @@ -25,4 +27,4 @@ client.search({ console.log('every "test" title', allTitles); } }); ---------- +--------- \ No newline at end of file diff --git a/docs/api_methods.asciidoc b/docs/api_methods.asciidoc index 7a1f1ace7..899c0b996 100644 --- a/docs/api_methods.asciidoc +++ b/docs/api_methods.asciidoc @@ -1663,7 +1663,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. diff --git a/docs/api_methods_0_90.asciidoc b/docs/api_methods_0_90.asciidoc index 09da3c043..23f6ad2d4 100644 --- a/docs/api_methods_0_90.asciidoc +++ b/docs/api_methods_0_90.asciidoc @@ -1132,7 +1132,6 @@ client.search({ --------- - *Params* [horizontal] @@ -1155,7 +1154,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/fullscale/elastic.js[elastic.js], https://github.com/holidayextras/esq[esq], or https://github.com/danpaz/bodybuilder[bodybuilder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], and https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier. diff --git a/docs/api_methods_1_7.asciidoc b/docs/api_methods_1_7.asciidoc index 46dbfac57..0c2f50a63 100644 --- a/docs/api_methods_1_7.asciidoc +++ b/docs/api_methods_1_7.asciidoc @@ -1625,7 +1625,6 @@ client.search({ --------- - *Params* [horizontal] @@ -1648,7 +1647,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/fullscale/elastic.js[elastic.js], https://github.com/holidayextras/esq[esq], or https://github.com/danpaz/bodybuilder[bodybuilder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], and https://github.com/fullscale/elastic.js[elastic.js] can be used to make building query bodies easier. diff --git a/docs/api_methods_2_4.asciidoc b/docs/api_methods_2_4.asciidoc index 5ca431da5..6be56d9ba 100644 --- a/docs/api_methods_2_4.asciidoc +++ b/docs/api_methods_2_4.asciidoc @@ -1537,7 +1537,6 @@ client.search({ --------- - *Params* [horizontal] @@ -1560,7 +1559,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/fullscale/elastic.js[elastic.js], https://github.com/holidayextras/esq[esq], https://github.com/danpaz/bodybuilder[bodybuilder], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/sudo-suhas/elastic-builder[elastic-builder], and https://github.com/holidayextras/esq[esq] can be used to make building query bodies easier. diff --git a/docs/api_methods_5_0.asciidoc b/docs/api_methods_5_0.asciidoc index 707f81347..27d94633d 100644 --- a/docs/api_methods_5_0.asciidoc +++ b/docs/api_methods_5_0.asciidoc @@ -1665,7 +1665,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. diff --git a/docs/api_methods_5_1.asciidoc b/docs/api_methods_5_1.asciidoc index 4c5e5978e..f1a9281ca 100644 --- a/docs/api_methods_5_1.asciidoc +++ b/docs/api_methods_5_1.asciidoc @@ -1663,7 +1663,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. diff --git a/docs/api_methods_5_2.asciidoc b/docs/api_methods_5_2.asciidoc index c9e16fc05..fde12fec5 100644 --- a/docs/api_methods_5_2.asciidoc +++ b/docs/api_methods_5_2.asciidoc @@ -1663,7 +1663,7 @@ client.search([params, [callback]]) Return documents matching a query, aggregations/facets, highlighted snippets, suggestions, and more. Write your queries as either http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-uri-request.html[simple query strings] in the `q` parameter, or by specifying a http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html[full request definition] using the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl.html[Elasticsearch Query DSL] in the `body` parameter. -TIP: https://github.com/danpaz/bodybuilder[bodybuilder], https://github.com/holidayextras/esq[esq], or https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. +TIP: https://github.com/danpaz/bodybuilder[bodybuilder] and https://github.com/sudo-suhas/elastic-builder[elastic-builder] can be used to make building query bodies easier. diff --git a/package.json b/package.json index 448a9cd5c..d2642c2af 100644 --- a/package.json +++ b/package.json @@ -36,10 +36,7 @@ "unstable_es_branches": [ "5.x", "master" - ], - "branch_versions": { - "master": "6.0" - } + ] }, "devDependencies": { "@spalger/eslint-config-personal": "^0.4.0", diff --git a/scripts/Version.js b/scripts/Version.js index e7a0624eb..e685ae393 100644 --- a/scripts/Version.js +++ b/scripts/Version.js @@ -1,13 +1,34 @@ var _ = require('lodash'); var pkg = require('../package.json'); -var branches = pkg.config.supported_es_branches; -var branchVersions = pkg.config.branch_versions; +var branches = [...pkg.config.supported_es_branches, ...pkg.config.unstable_es_branches]; var semver = require('semver'); -var maxMinorVersion = function (majorV) { - var versions = branches.map(function (v) { return v + '.0'; }); - return new Version(semver.maxSatisfying(versions, '^' + majorV)); -}; +function nextMajorVersion() { + const largestMajor = branches + .map(v => parseFloat(v.split('.')[0])) + .filter(n => !isNaN(n)) + .sort((a, b) => b - a) + .shift() + + return new Version(`${largestMajor + 1}.0.0`) +} + +function nextMinorVersion(major) { + const largestMinor = branches + .map(v => v.split('.').map(parseFloat).slice(0, 2)) + // ensure all tuples have length 2 + .filter(vt => vt.length === 2) + // ensure all values in tuples are not NaN + .filter(vt => vt.every(v => !isNaN(v))) + // ensure that major version in tuple matches major (both as a string) + .filter(vt => `${vt[0]}` === `${major}`) + // sort by the minor version in each tuple + .sort((vta, vtb) => vtb[1] - vta[1]) + // get the minor version from the first tuple + .shift()[1]; + + return new Version(`${major}.${largestMinor + 1}.0`); +} function Version(v) { this.version = v; @@ -17,16 +38,15 @@ function Version(v) { } Version.fromBranch = function (branch) { - var m; - - var branchVersion = branchVersions[branch]; - var versionString = branchVersion ? branchVersion : branch; - // n.m -> n.m.0 - if (m = versionString.match(/^\d+\.\d+$/)) return new Version(versionString + '.0'); + if (/^\d+\.\d+$/.test(branch)) return new Version(branch + '.0'); // n.x -> n.(maxVersion + 1).0 - if (m = versionString.match(/^(\d+)\.x$/i)) return maxMinorVersion(m[1]).increment('minor'); + const match = branch.match(/^(\d+)\.x$/i) + if (match) return nextMinorVersion(match[1]); + + // master => (maxMajorVersion + 1).0.0 + if (branch === 'master') return nextMajorVersion() throw new Error('unable to convert branch "' + branch + '" to semver'); }; @@ -36,6 +56,7 @@ Version.prototype.increment = function (which) { }; Version.prototype.satisfies = function (range) { + debugger return semver.satisfies(this.version, range); }; diff --git a/scripts/generate/js_api.js b/scripts/generate/js_api.js index 0a4a06a6e..edaa1f203 100644 --- a/scripts/generate/js_api.js +++ b/scripts/generate/js_api.js @@ -27,7 +27,8 @@ module.exports = function (branch, done) { mergeConcatParams: {}, paramAsBody: {}, clientActionModifier: false, - examples: {} + examples: {}, + descriptions: {}, }); var steps = [ @@ -115,12 +116,19 @@ module.exports = function (branch, done) { [].concat(apiSpec.actions, apiSpec.proxies) .forEach(function (action) { var examplePath = overrides.examples[action.name] || action.name + '.asciidoc'; + var descriptionPath = overrides.descriptions[action.name] || action.name + '.asciidoc'; try { action.examples = fs.readFileSync(fromRoot('docs/_examples', examplePath), 'utf8'); } catch (e) { action.examples = '// no examples'; } + + try { + action.description = fs.readFileSync(fromRoot('docs/_descriptions', descriptionPath), 'utf8'); + } catch (e) { + action.description = '// no description'; + } }) done(); diff --git a/scripts/generate/overrides.js b/scripts/generate/overrides.js index 4076462a0..ee406a062 100644 --- a/scripts/generate/overrides.js +++ b/scripts/generate/overrides.js @@ -249,9 +249,6 @@ function (spec) { '/_update_by_query/{task_id}/_rethrottle', '/_delete_by_query/{task_id}/_rethrottle' ] - }, - examples: { - scroll: 'scroll_5.0+.asciidoc' } }, { @@ -266,5 +263,31 @@ function (spec) { body: 'scroll_id' } } + }, + // description overrides by major version + { + version: '0.90.x', + descriptions: { + search: 'search_1.x.asciidoc' + } + }, + { + version: '1.x', + descriptions: { + search: 'search_1.x.asciidoc' + } + }, + { + version: '2.x', + descriptions: { + search: 'search_2.x.asciidoc' + } + }, + // examples changed at 5.0 + { + version: '<5.0.0', + examples: { + scroll: 'scroll_<5.0.asciidoc' + } } ]; diff --git a/scripts/generate/templates/api_methods.tmpl b/scripts/generate/templates/api_methods.tmpl index c7cecd050..5e8bc1393 100644 --- a/scripts/generate/templates/api_methods.tmpl +++ b/scripts/generate/templates/api_methods.tmpl @@ -21,7 +21,7 @@ _.each(actions, function (action) { client.<%= action.name %>([params, [callback]]) -------- -<%= description(action.name) %> +<%= action.description %> Check the *<>* and <%= action.docUrl %>[the elasticsearch docs] for more information pertaining to this method. diff --git a/scripts/generate/templates/index.js b/scripts/generate/templates/index.js index 97256ebf3..aec6069dd 100644 --- a/scripts/generate/templates/index.js +++ b/scripts/generate/templates/index.js @@ -54,18 +54,6 @@ var templateGlobals = { return block.split('\n\n').join('\n+\n'); }, - description: function (action) { - try { - return fs.readFileSync(path.join(__dirname, '../../../docs/_descriptions/' + action + '.asciidoc')); - } catch (e) { - if (~e.message.indexOf('ENOENT')) { - return '// no description'; - } else { - throw e; - } - } - }, - paramType: function (type, paramName) { switch (type && type.toLowerCase ? type.toLowerCase() : 'any') { case 'time':