Restructure reference docs

Author: swallez

docs/docset.yml

@@ -2,7 +2,6 @@ project: 'Java API Client'
 exclude:
   - external-resources.md
   - design/*
-  - local/README.md
 cross_links:
   - docs-content
   - elasticsearch
@@ -13,3 +12,4 @@ subs:
   serverless-full:   "Elastic Cloud Serverless"
   es3:   "Elasticsearch Serverless"
   es:   "Elasticsearch"
+  version: "9.0.0"

docs/local/README.md

@@ -0,0 +1 @@
+The source code for the examples above can be found in the [Java API Client tests](https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/test/java/co/elastic/clients/documentation).

docs/reference/_snippets/doc-tests-blurb.md

@@ -9,6 +9,13 @@ API clients come in two flavors: blocking and asynchronous. All methods on async
 
 Both flavors can be used at the same time depending on your needs, sharing the same transport object:
 
+<!-- :::include
+```java
+ElasticsearchTransport transport = ...
+:::{include} {doc-tests-src}/api_conventions/ApiConventionsTest.java[blocking-and-async]
+```
+-->
+
 ```java
 ElasticsearchTransport transport = ...
 
@@ -36,5 +43,6 @@ asyncClient
 
 Although we won’t go in deeper details on asynchronous programming in Java, remember to handle failures of asynchronous tasks. It’s easy to overlook them and have errors go unnoticed.
 
-The source code for the examples above can be found in the [Java API Client tests](https://github.com/elastic/elasticsearch-java/tree/master/java-client/src/test/java/co/elastic/clients/documentation).
+:::{include} /reference/_snippets/doc-tests-blurb.md
+:::
 

docs/reference/api-conventions.md

@@ -99,5 +99,6 @@ SearchResponse<SomeApplicationData> results = client
 1. Search results will be mapped to `SomeApplicationData` instances to be readily available to the application.
 
 
-The source code for the examples above can be found in the [Java API Client tests](https://github.com/elastic/elasticsearch-java/tree/master/java-client/src/test/java/co/elastic/clients/documentation).
+:::{include} /reference/_snippets/doc-tests-blurb.md
+:::
 

docs/reference/blocking-async.md …erence/api-conventions/blocking-async.mddocs/reference/blocking-async.md renamed to docs/reference/api-conventions/blocking-async.md docs/reference/blocking-async.md renamed to docs/reference/api-conventions/blocking-async.md

@@ -0,0 +1,28 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/api-conventions.html
+---
+
+# API conventions [api-conventions]
+
+The Java API Client uses a very consistent code structure, using modern code patterns that make complex requests easier to write and complex responses easier to process. The sections below explain these in details.
+
+* [Package structure and namespace clients](package-structure.md)
+* [Method naming conventions](method-naming.md)
+* [Blocking and asynchronous clients](blocking-async.md)
+* [Building API objects](building-objects.md)
+* [Lists and maps](lists-maps.md)
+* [Variant types](variant-types.md)
+* [Object life cycles and thread safety](object-lifecycles.md)
+* [Creating API objects from JSON data](loading-json.md)
+* [Exceptions](exception-conventions.md)
+
+
+
+
+
+
+
+
+
+

docs/reference/building-objects.md …ence/api-conventions/building-objects.mddocs/reference/building-objects.md renamed to docs/reference/api-conventions/building-objects.md docs/reference/building-objects.md renamed to docs/reference/api-conventions/building-objects.md

@@ -73,5 +73,6 @@ assertEquals(0, stats.failures().size());
 assertFalse(ApiTypeHelper.isDefined(stats.failures()));
 ```
 
-The source code for the examples above can be found in the [Java API Client tests](https://github.com/elastic/elasticsearch-java/tree/master/java-client/src/test/java/co/elastic/clients/documentation).
+:::{include} /reference/_snippets/doc-tests-blurb.md
+:::
 

docs/reference/exception-conventions.md …api-conventions/exception-conventions.mddocs/reference/exception-conventions.md renamed to docs/reference/api-conventions/exception-conventions.md docs/reference/exception-conventions.md renamed to docs/reference/api-conventions/exception-conventions.md

@@ -167,5 +167,6 @@ Map<String, Aggregate> aggs = client
 
 Notice that order matters when the JSON snippets have some common properties: just as when setting property values programmatically, the last value that is set for a property overwrites the previous one.
 
-The source code for the examples above can be found in the [Java API Client tests](https://github.com/elastic/elasticsearch-java/tree/master/java-client/src/test/java/co/elastic/clients/documentation).
+:::{include} /reference/_snippets/doc-tests-blurb.md
+:::