From 23b8b972755ed5925c3f790544f056bca5fb5cb6 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Mon, 20 Mar 2017 14:50:19 -0400 Subject: [PATCH] Use include-tagged macro for high level client docs (#23438) This should make it simpler to include example snippets from tests. --- .../documentation/DeleteDocumentationIT.java | 24 ++++++++--------- .../high-level/document/delete.asciidoc | 26 +++++++++---------- .../high-level/document/index.asciidoc | 4 +++ 3 files changed, 29 insertions(+), 25 deletions(-) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java index ddb96cdc00e..00c19019f47 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java @@ -56,35 +56,35 @@ public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase { public void testDelete() throws IOException { RestHighLevelClient client = highLevelClient(); - // tag::delete-request[] + // tag::delete-request DeleteRequest request = new DeleteRequest( "index", // <1> "type", // <2> "id"); // <3> - // end::delete-request[] + // end::delete-request - // tag::delete-request-props[] + // tag::delete-request-props request.timeout(TimeValue.timeValueSeconds(1)); // <1> request.timeout("1s"); // <2> request.setRefreshPolicy(WriteRequest.RefreshPolicy.WAIT_UNTIL); // <3> request.setRefreshPolicy("wait_for"); // <4> request.version(2); // <5> request.versionType(VersionType.EXTERNAL); // <6> - // end::delete-request-props[] + // end::delete-request-props - // tag::delete-execute[] + // tag::delete-execute DeleteResponse response = client.delete(request); - // end::delete-execute[] + // end::delete-execute try { - // tag::delete-notfound[] + // tag::delete-notfound if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) { throw new Exception("Can't find document to be removed"); // <1> } - // end::delete-notfound[] + // end::delete-notfound } catch (Exception ignored) { } - // tag::delete-execute-async[] + // tag::delete-execute-async client.deleteAsync(request, new ActionListener() { @Override public void onResponse(DeleteResponse deleteResponse) { @@ -96,9 +96,9 @@ public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase { // <2> } }); - // end::delete-execute-async[] + // end::delete-execute-async - // tag::delete-conflict[] + // tag::delete-conflict try { client.delete(request); } catch (ElasticsearchException exception) { @@ -106,7 +106,7 @@ public class DeleteDocumentationIT extends ESRestHighLevelClientTestCase { // <1> } } - // end::delete-conflict[] + // end::delete-conflict } } diff --git a/docs/java-rest/high-level/document/delete.asciidoc b/docs/java-rest/high-level/document/delete.asciidoc index 36cfc54994e..e9ba8b19408 100644 --- a/docs/java-rest/high-level/document/delete.asciidoc +++ b/docs/java-rest/high-level/document/delete.asciidoc @@ -6,19 +6,20 @@ The most simple Delete Request needs is: -["source","java",subs="attributes,callouts"] +["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -sys2::[perl -ne 'exit if /end::delete-request/; print if $tag; $tag = $tag || /tag::delete-request/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] +include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request] -------------------------------------------------- <1> Index name <2> Type <3> Document id + You can also provide the following properties: -["source","java",subs="attributes,callouts"] +["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -sys2::[perl -ne 'exit if /end::delete-request-props/; print if $tag; $tag = $tag || /tag::delete-request-props/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] +include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-request-props] -------------------------------------------------- <1> Timeout <2> Timeout as String @@ -30,17 +31,17 @@ sys2::[perl -ne 'exit if /end::delete-request-props/; print if $tag; $tag = $tag [[java-rest-high-document-delete-sync]] ==== Execution -["source","java",subs="attributes,callouts"] +["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -sys2::[perl -ne 'exit if /end::delete-execute/; print if $tag; $tag = $tag || /tag::delete-execute/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] +include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute] -------------------------------------------------- [[java-rest-high-document-delete-async]] ==== Asynchronous Execution -["source","java",subs="attributes,callouts"] +["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -sys2::[perl -ne 'exit if /end::delete-execute-async/; print if $tag; $tag = $tag || /tag::delete-execute-async/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] +include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-execute-async] -------------------------------------------------- <1> Implement if needed when execution did not throw an exception <2> Implement if needed in case of failure @@ -50,18 +51,17 @@ sys2::[perl -ne 'exit if /end::delete-execute-async/; print if $tag; $tag = $tag In the Delete Response object, you can check for example the result of the operation: -["source","java",subs="attributes,callouts"] +["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -sys2::[perl -ne 'exit if /end::delete-notfound/; print if $tag; $tag = $tag || /tag::delete-notfound/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] +include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-notfound] -------------------------------------------------- <1> Do something if we did not find the document which should have been deleted Note that if you have a version conflict because you defined the version within the <>, it will raise an `ElasticsearchException` like: -["source","java",subs="attributes,callouts"] +["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- -sys2::[perl -ne 'exit if /end::delete-conflict/; print if $tag; $tag = $tag || /tag::delete-conflict/' {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java] +include-tagged::{doc-tests}/DeleteDocumentationIT.java[delete-conflict] -------------------------------------------------- <1> We got a version conflict - diff --git a/docs/java-rest/high-level/document/index.asciidoc b/docs/java-rest/high-level/document/index.asciidoc index 15eee483baa..32815794a1b 100644 --- a/docs/java-rest/high-level/document/index.asciidoc +++ b/docs/java-rest/high-level/document/index.asciidoc @@ -1 +1,5 @@ +:doc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client/documentation + include::delete.asciidoc[] + +:doc-tests!: