From aa2292b5931decdc2427d6c04235729e7b883707 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Wed, 1 Mar 2017 13:33:39 -0500 Subject: [PATCH] Use include-tagged macro for high level client docs 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 591e4d7ebbd9e..712051c78d3f2 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 @@ -55,35 +55,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) { @@ -95,9 +95,9 @@ public void onFailure(Exception e) { // <2> } }); - // end::delete-execute-async[] + // end::delete-execute-async - // tag::delete-conflict[] + // tag::delete-conflict try { client.delete(request); } catch (ElasticsearchException exception) { @@ -105,7 +105,7 @@ public void onFailure(Exception e) { // <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 36cfc54994e62..e9ba8b1940856 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 15eee483baab0..32815794a1ba2 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!: