Merge pull request #629 from cescoffier/fix-doc

Fix documentation snippets
smallrye · Jul 25, 2023 · dbc1a6d · dbc1a6d
2 parents eebca7e + ee012d4
commit dbc1a6d
Show file tree

Hide file tree

Showing 12 changed files with 35 additions and 26 deletions.
diff --git a/docs/docs/concepts.md b/docs/docs/concepts.md
@@ -33,7 +33,7 @@ The `Stork` instance is a _singleton_.
 It needs to be initialized once (when the application starts) and shutdown when the application stops:
 
 ```java linenums="1"
---8<-- "snippets/examples/StorkEntryPointExample.java"
+{{ insert('examples/StorkEntryPointExample.java') }}
 ```
 
 During the initialization, Stork looks for `io.smallrye.stork.config.ConfigProvider` SPI provider and CDI beans (from 2.x version) and retrieves the list of managed services:
@@ -49,7 +49,7 @@ Services are pre-configured with their name, service discovery, and optionally,
 You retrieve a `Service` using the `Stork#getService(String name)` method.
 
 ```java linenums="1"
---8<-- "snippets/examples/StorkServiceExample.java"
+{{ insert('examples/StorkServiceExample.java') }}
 ```
 
 The `Service` lets you retrieve the list of `ServiceInstance`, or select a single one, when a load-balancer is configured.
@@ -60,7 +60,7 @@ The `io.smallrye.stork.api.ServiceInstance` represents an actual instance of the
 It provides the metadata to configure a _client_ to interact with that specific instance of service.
 
 ```java linenums="1"
---8<-- "snippets/examples/StorkServiceLookupExample.java"
+{{ insert('examples/StorkServiceLookupExample.java') }}
 ```
 
 The service selection is a two-steps process:
@@ -69,7 +69,7 @@ The service selection is a two-steps process:
 2. Service selection - using the load balancer
 
 ```java linenums="1"
---8<-- "snippets/examples/StorkServiceSelectionExample.java"
+{{ insert('examples/StorkServiceSelectionExample.java') }}
 ```
 
 ## Service Discovery

diff --git a/docs/docs/extra.css b/docs/docs/extra.css
@@ -1,3 +1,10 @@
 .md-header__title {
     margin-left: 0 !important;
-}
+}
+
+img {
+    margin-left: auto;
+    margin-right: auto;
+    max-width: 80% !important;
+}
+
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -24,6 +24,7 @@ Nevertheless, a modern distributed system or microservice-based application typi
 IPs get randomly assigned, and instances can be created or destroyed at any time.
 With such dynamics, hard-coded locations are a dead-end.
 
+
 ![the problem](images/problem-light.png#only-light)
 ![the problem](images/problem-dark.png#only-dark)
 

diff --git a/docs/docs/load-balancer/custom-load-balancer.md b/docs/docs/load-balancer/custom-load-balancer.md
@@ -50,7 +50,7 @@ Optionally, you can also add `@ApplicationScoped` annotation in order to provide
 
 A load balancer provider class should look as follows:
 ```java linenums="1"
---8<-- "snippets/examples/AcmeLoadBalancerProvider.java"
+{{ insert('examples/AcmeLoadBalancerProvider.java') }}
 ```
 
 Note, that the `LoadBalancerProvider` interface takes a configuration class as a parameter. 
@@ -62,7 +62,7 @@ The next step is to implement the `LoadBalancer` interface.
 The essence of load balancers' work happens in the `selectServiceInstance` method. The method returns a single `ServiceInstance` from a collection. 
 
 ```java linenums="1"
---8<-- "snippets/examples/AcmeLoadBalancer.java"
+{{ insert('examples/AcmeLoadBalancer.java') }}
 ```
 
 This implementation is simplistic and just picks a random instance from the received list.
@@ -99,7 +99,7 @@ When building your load balancer project, the configuration generator creates a
 This class can be used to configure your load balancer using the Stork programmatic API. 
 
 ```java linenums="1"
---8<-- "snippets/examples/AcmeSelectorApiUsage.java"
+{{ insert('examples/AcmeSelectorApiUsage.java') }}
 ```
 
 Remember that attributes, like `my-attribute`, are declared using the `@LoadBalancerAttribute` annotation on the `LoadBalancerProvider` implementation.
diff --git a/docs/docs/programmatic-api.md b/docs/docs/programmatic-api.md
@@ -13,15 +13,15 @@ Retrieve the ServiceInstance, which will provide the metadata to access the actu
 If your framework does not already provide a configured `Stork` instance, you need to do:
 
 ```java linenums="1"
---8<-- "snippets/examples/InitializationExample.java"
+{{ insert('examples/InitializationExample.java') }}
 ```
 
 ## Adding service dynamically
 
 To register a new `ServiceDefinition`, use the `defineIfAbsent` method:
 
 ```java linenums="1"
---8<-- "snippets/examples/DefinitionExample.java"
+{{ insert('examples/DefinitionExample.java') }}
 ```
 
 The `ServiceDefinition` instances can be created from:
@@ -36,7 +36,7 @@ Attributes from the service discovery and load balancer can be configured from t
 To list the service instances for a given service, or to select an instance according to the load balancer strategy, use the following code:
 
 ```java linenums="1"
---8<-- "snippets/examples/LookupExample.java"
+{{ insert('examples/LookupExample.java') }}
 ```
 
 The lookup and selection methods are returning Uni as these processes are asynchronous.
@@ -46,5 +46,5 @@ The lookup and selection methods are returning Uni as these processes are asynch
 The following snippet provides an _all in one_ example of the Stork programmatic API:
 
 ```java linenums="1"
---8<-- "snippets/examples/StorkApiExample.java"
+{{ insert('examples/StorkApiExample.java') }}
 ```
diff --git a/docs/docs/quarkus.md b/docs/docs/quarkus.md
@@ -24,7 +24,7 @@ To use Stork to determine the actual address, set the scheme of the URI to `stor
 
 For example, the `HelloClient` below will use the Stork service called `hello-service` to determine the address of the destination, and `/hello` as the base path for queries:
 ```java linenums="1"
---8<-- "snippets/examples/HelloClient.java"
+{{ insert('examples/HelloClient.java') }}
 ```
 
 ## The service

diff --git a/docs/docs/service-discovery/custom-service-discovery.md b/docs/docs/service-discovery/custom-service-discovery.md
@@ -50,7 +50,7 @@ Optionally, you can also add `@ApplicationScoped` annotation in order to provide
 A service discovery provider class should look as follows:
 
 ```java linenums="1"
---8<-- "snippets/examples/AcmeServiceDiscoveryProvider.java"
+{{ insert('examples/AcmeServiceDiscoveryProvider.java') }}
 ```
 
 Note, that the `ServiceDiscoveryProvider` interface takes a configuration class as a parameter. This configuration class 
@@ -60,7 +60,7 @@ Its name is created by appending `Configuration` to the service discovery type,
 The next step is to implement the `ServiceDiscovery` interface:
 
 ```java linenums="1"
---8<-- "snippets/examples/AcmeServiceDiscovery.java"
+{{ insert('examples/AcmeServiceDiscovery.java') }}
 ```
 
 This implementation is simplistic.
@@ -98,7 +98,7 @@ When building your service discovery project, the configuration generator create
 This class can be used to configure your service discovery using the Stork programmatic API.
 
 ```java linenums="1"
---8<-- "snippets/examples/AcmeDiscoveryApiUsage.java"
+{{ insert('examples/AcmeDiscoveryApiUsage.java') }}
 ```
 
 Remember that attributes, like `host`, are declared using the `@ServiceDiscoveryAttribute` annotation on the `ServiceDiscoveryProvider` implementation.
@@ -118,13 +118,13 @@ For homogeneity, we recommend the following attribute:
 The following snippet extends the _acme_ service discovery with the `refresh-period` attribute:
 
 ```java linenums="1"
---8<-- "snippets/examples/CachedAcmeServiceDiscoveryProvider.java"
+{{ insert('examples/CachedAcmeServiceDiscoveryProvider.java') }}
 ```
 
 Extending `io.smallrye.stork.impl.CachingServiceDiscovery` changes the structure of the service discovery implementation:
 
 ```java linenums="1"
---8<-- "snippets/examples/CachedAcmeServiceDiscovery.java"
+{{ insert('examples/CachedAcmeServiceDiscovery.java') }}
 ```
 
 1. Call the `super` constructor with the `refresh-period` value

diff --git a/docs/docs/service-discovery/knative.md b/docs/docs/service-discovery/knative.md
@@ -38,7 +38,7 @@ A `ServiceAccount`, a `Role` and a `RoleBinding` are needed in order to allow St
 An example that allows listing all endpoints could look something like this:
 
 ```yaml
-------
+---
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -104,8 +104,6 @@ Contacting the cluster too much frequently can result in performance problems. I
 Moreover, the caching expiration has been also improved in order to only update the retrieved set of `ServiceInstance` if some of them changes and an event is emitted. 
 This is done by creating an [Informer](https://www.javadoc.io/static/io.fabric8/kubernetes-client-api/6.1.1/io/fabric8/kubernetes/client/informers/SharedIndexInformer.html), similar to a [Watch](https://www.javadoc.io/static/io.fabric8/kubernetes-client-api/6.1.1/io/fabric8/kubernetes/client/Watch.html),  able to observe the events on the Knative Service instances resources. 
 
---8<-- "../src/main/java/io/smallrye/stork/servicediscovery/knative/KnativeServiceDiscovery.java"
-
 Note that: 
  - the cache is invalidated when an event is received. 
  - the cache is validated once the instances are retrieved from the cluster, in the `fetchNewServiceInstances` method.

diff --git a/docs/docs/service-discovery/kubernetes.md b/docs/docs/service-discovery/kubernetes.md
@@ -104,8 +104,6 @@ Contacting the cluster too much frequently can result in performance problems. I
 Moreover, the caching expiration has been also improved in order to only update the retrieved set of `ServiceInstance` if some of them changes and an event is emitted. 
 This is done by creating an [Informer](https://www.javadoc.io/static/io.fabric8/kubernetes-client-api/6.1.1/io/fabric8/kubernetes/client/informers/SharedIndexInformer.html), similar to a [Watch](https://www.javadoc.io/static/io.fabric8/kubernetes-client-api/6.1.1/io/fabric8/kubernetes/client/Watch.html),  able to observe the events on the service instances resources. 
 
---8<-- "../src/main/java/io/smallrye/stork/servicediscovery/kubernetes/KubernetesServiceDiscovery.java"
-
 Note that: 
  - the cache is invalidated when an event is received. 
  - the cache is validated once the instances are retrieved from the cluster, in the `fetchNewServiceInstances` method.

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -112,7 +112,10 @@ plugins:
       theme_folder: "include/themes"
       theme_light: "light.puml"
       theme_dark: "dark.puml"
-  - macros
+  - macros:
+      verbose: true
+      module_name: mkdocs-customizations/macros/docissimo
+      include_dir: mkdocs-customizations/macros
 
 
 extra:

diff --git a/docs/snippets/examples/DefinitionExample.java b/docs/snippets/examples/DefinitionExample.java
@@ -22,7 +22,8 @@ public static void example(Stork stork) {
                 ServiceDefinition.of(new StaticConfiguration().withAddressList(example),
                         new RandomConfiguration()));
 
-        // Another service using the random selection strategy, instead of round-robin and a static service registrar
+        // Another service using the random selection strategy, instead of round-robin
+        // and a static service registrar
         stork.defineIfAbsent("my-second-service",
                 ServiceDefinition.of(new StaticConfiguration().withAddressList(example),
                         new RandomConfiguration(), new StaticRegistrarConfiguration()));

diff --git a/docs/snippets/examples/StorkApiExample.java b/docs/snippets/examples/StorkApiExample.java
@@ -31,7 +31,8 @@ public static void main(String[] args) {
                 .await().atMost(Duration.ofSeconds(1));
         System.out.println(instance.getHost() + ":" + instance.getPort());
 
-        // Another service using the random selection strategy, instead of round-robin and a static service registrar
+        // Another service using the random selection strategy, instead of round-robin
+        // and a static service registrar
         stork.defineIfAbsent("my-third-service",
                 ServiceDefinition.of(new StaticConfiguration().withAddressList(example),
                         new RandomConfiguration(), new StaticRegistrarConfiguration()));