Add first High level client documentation #23351

dadoonet · 2017-02-24T12:59:28Z

The REST Client is split into 2 parts:

Low level
High level

The High level client has a main common section and the document delete API documentation as a start.

I'd really like that we have a QA module where we test all the methods we are documenting and even better only include code snippets into the documentation so we know it's always up to date.

I'd like to start with a QA project if no one objects.

The REST Client is split into 2 parts: * Low level * High level The High level client has a main common section and the document delete API documentation as a start.

nik9000 · 2017-02-27T15:34:09Z

client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java

+        RestHighLevelClient client = highLevelClient();
+
+// tag::delete-request[]
+DeleteRequest request = new DeleteRequest(


I'd use normal indenting here. I think we can strip them in the magic perl script if we really want to.

That'd be lovely as this formatting is a pain for now.
I'm going to change that in the source code then but can you tell me how I can fix the rendering then?

I'd commit with the indented format and fix in a followup. I'm thinking of writing a little fancier perl script in a followup.

nik9000 · 2017-02-27T15:34:46Z

client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java

+import java.io.IOException;
+
+/**
+ * This class is used to generate the Java API documentation


I'd add a note about how the tags are resolved. Just because this is the first usage.

nik9000 · 2017-02-27T15:45:16Z

client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java

+
+// tag::delete-notfound[]
+if (response.getResult().equals(DocWriteResponse.Result.NOT_FOUND)) {
+    // <1>


Maybe throw an exception from here just so the docs look more realistic?

nik9000 · 2017-02-27T15:49:16Z

docs/java-rest/high-level/document/delete.asciidoc

+
+["source","java",subs="attributes,callouts"]
+--------------------------------------------------
+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/DocumentationIT.java]


I wonder if it is worth dumping the script into the root of the doc directory so you don't have to repeat it? On second thought, maybe just add it like it is now and I'll see about making a followup? I have some ideas - maybe write an asciidoc macro or something.

Let's keep it simple for now but that would be lovely to have a gradle task which does that extraction for instance and generate all the doc so we don't call anymore build_docs.pl but gradle docs or something.

nik9000 · 2017-02-27T15:49:47Z

docs/java-rest/high-level/document/delete.asciidoc

+
+[source,java]
+--------------------------------------------------
+try {


Do you want to reference this from the file? I think it'd be nice if everything came from a file.

Indeed. Not sure why I did not write it like this... o_O

nik9000 · 2017-02-27T15:52:10Z

client/rest-high-level/src/test/java/org/elasticsearch/client/DocumentationIT.java

+/**
+ * This class is used to generate the Java API documentation
+ */
+public class DocumentationIT extends ESRestHighLevelClientTestCase {


Maybe DeleteDocumentationIT. Also maybe put in org.elasticsearch.client.documentation?

nik9000 · 2017-02-27T15:54:07Z

docs/java-rest/high-level/usage.asciidoc

+
+Then you have access to the high level APIs such as:
+
+include::apis.asciidoc[]


Link instead of include here? I'm not sure.

I found out that it gives a better documentation as the guy does not have to clic but has everything at hand.

nik9000 · 2017-02-27T15:57:32Z

docs/java-rest/high-level/usage.asciidoc

+
+include::apis.asciidoc[]
+
+Each API comes with 2 ways of executing it:


I think it'd be easier to write something like:

Each API can be executed synchronously (i.e. `delete`) or asynchronously (i.e. `deleteAysnc`). The asynchronous APIs require a listener that is called on thread pool managed by the low level client when the response is received.

nik9000 · 2017-02-27T19:44:33Z

I'd really like that we have a QA module where we test all the methods we are documenting and even better only include code snippets into the documentation so we know it's always up to date.

We could put the test in the docs build instead of into the qa module. It is functionally quite similar to the testing we do in the docs build right now.

javanna · 2017-02-24T13:06:36Z

docs/java-rest/high-level/usage.asciidoc

+elasticsearch. Replace the version with the desired client version, first
+released with `5.x.x`. There is no relation between the client version
+and the elasticsearch version that the client can communicate with as
+it depends on the <<java-rest-low>> which is compatible with all elasticsearch versions.


I'm afraid this will have to be rephrased. If 5.y adds some fields to the response, only version 5.y of the high level client will support that addition. the versions are more important compared to the low level client. Maybe just stop at "Replace the version with the desired client version" ?

dadoonet · 2017-03-01T10:52:07Z

@nik9000 @javanna Thanks guys for your comments. I pushed new changes. LMK

nik9000 · 2017-03-01T12:14:19Z

...t-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java

+import java.io.IOException;
+
+/**
+ * This class is used to generate the Java Delete API documentation


Add a . to the end of this line.

Yeah. I also fixed a missing parenthesis in code...

nik9000 · 2017-03-01T12:15:22Z

docs/java-rest/high-level/usage.asciidoc

+
+Then you have access to the high level APIs such as:
+
+include::apis.asciidoc[]


nik9000

Looks fine to me. The docs don't compile though.

nik9000 · 2017-03-01T12:28:24Z

The docs don't compile though.

I believe it is hitting the example tag at the top instead of lower.

nik9000 · 2017-03-01T12:28:40Z

...t-high-level/src/test/java/org/elasticsearch/client/documentation/DeleteDocumentationIT.java

+/**
+ * This class is used to generate the Java Delete API documentation.
+ * You need to wrap your code between two tags like:
+ * // tag::delete-request[]


Change this to // tag:example[]

dadoonet · 2017-03-01T12:35:22Z

I'm going to fix this bad rendering as well...

dadoonet · 2017-03-01T12:36:33Z

Actually the rendering is "bad" because of the indentation. If we fix indentation, this problem will go away.

dadoonet · 2017-03-01T12:49:12Z

Thanks @nik9000. Merged in master.

javanna · 2017-03-01T13:11:50Z

thanks @dadoonet ! Once the high level rest client is ready for its first release, we will backport it to 5.x, and that will simply mean copying the high-level folder in a single commit. We will also have to backport the docs, but I see that this PR changes some things outside of the high-level directory, and I understand there will be subsequent changes going in. I wonder how complicated it will be come to backport the docs when we need to. Any ideas on that?

dadoonet · 2017-03-01T13:13:59Z

I don't think it will be a big deal as I don't recall having conflicts or anything like that in docs. I believe we can cherry-pick one or more of my commits from this PR.

javanna · 2017-03-01T13:44:48Z

sure @dadoonet that will mean that we need to take note of these commits and all the following ones on the matter. This is something highly likely to cause mess ups I'm afraid, I will be happy to be proven wrong :)

dadoonet · 2017-03-01T13:47:43Z

What is the other solution you have in mind?
Having doc alongside code? So if you have doc in client/rest-high-level/doc then it will be part or the copy/paste you mentioned?

javanna · 2017-03-01T13:49:53Z

I do not have another solution in mind, let's just keep this in mind for the future changes and try to keep them isolated to the high-level folder as much as possible.

As we are extracting our documentation from the code since elastic/elasticsearch#23351 we need to add the path to the source code when generating the documentation

Add first High level client documentation

60661ec

The REST Client is split into 2 parts: * Low level * High level The High level client has a main common section and the document delete API documentation as a start.

dadoonet added :Java High Level REST Client >docs General docs changes labels Feb 24, 2017

dadoonet self-assigned this Feb 24, 2017

Extract documentation from test code

c373ed1

nik9000 reviewed Feb 27, 2017

View reviewed changes

javanna reviewed Feb 28, 2017

View reviewed changes

dadoonet added 3 commits March 1, 2017 11:26

Merge branch 'master' into doc/hlclient-delete

6c526ad

Don't mention cluster compatibility

798bf96

Adapt per Nik's comments

ee4a17a

nik9000 reviewed Mar 1, 2017

View reviewed changes

Missing dot and parenthesis

2629c98

nik9000 approved these changes Mar 1, 2017

View reviewed changes

nik9000 reviewed Mar 1, 2017

View reviewed changes

Bad rendering of docs

dc80a1f

dadoonet merged commit dc80a1f into elastic:master Mar 1, 2017

dadoonet deleted the doc/hlclient-delete branch March 1, 2017 12:40

dadoonet added the v6.0.0-alpha1 label Mar 1, 2017

dadoonet added a commit to elastic/docs that referenced this pull request Mar 1, 2017

Add documentation source code

358f30c

As we are extracting our documentation from the code since elastic/elasticsearch#23351 we need to add the path to the source code when generating the documentation

nik9000 mentioned this pull request Mar 1, 2017

Use include-tagged macro for high level client docs #23438

Merged

dadoonet mentioned this pull request May 11, 2017

Improve Java API documentation with more detail and best practice examples #24604

Closed

javanna mentioned this pull request Jun 6, 2017

Backport high level REST client #25086

Merged


		Then you have access to the high level APIs such as:

		include::apis.asciidoc[]


		include::apis.asciidoc[]

		Each API comes with 2 ways of executing it:

Add first High level client documentation #23351

Add first High level client documentation #23351

Uh oh!

Conversation

dadoonet commented Feb 24, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nik9000 commented Feb 27, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dadoonet commented Mar 1, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nik9000 left a comment

Choose a reason for hiding this comment

Uh oh!

nik9000 commented Mar 1, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dadoonet commented Mar 1, 2017

Uh oh!

dadoonet commented Mar 1, 2017

Uh oh!

dadoonet commented Mar 1, 2017

Uh oh!

javanna commented Mar 1, 2017

Uh oh!

dadoonet commented Mar 1, 2017

Uh oh!

javanna commented Mar 1, 2017

Uh oh!

dadoonet commented Mar 1, 2017

Uh oh!

javanna commented Mar 1, 2017

Uh oh!

Reviewers