From ee012d4e5eb417eb52709bb65f567ea4a2ca5820 Mon Sep 17 00:00:00 2001 From: Clement Escoffier Date: Tue, 25 Jul 2023 13:18:27 +0200 Subject: [PATCH] Fix #626 The source code inclusion did not work, switch to docissimo "insert" macro --- docs/docs/concepts.md | 8 ++++---- docs/docs/extra.css | 9 ++++++++- docs/docs/index.md | 1 + docs/docs/load-balancer/custom-load-balancer.md | 6 +++--- docs/docs/programmatic-api.md | 8 ++++---- docs/docs/quarkus.md | 2 +- .../docs/service-discovery/custom-service-discovery.md | 10 +++++----- docs/docs/service-discovery/knative.md | 4 +--- docs/docs/service-discovery/kubernetes.md | 2 -- docs/mkdocs.yml | 5 ++++- docs/snippets/examples/DefinitionExample.java | 3 ++- docs/snippets/examples/StorkApiExample.java | 3 ++- 12 files changed, 35 insertions(+), 26 deletions(-) diff --git a/docs/docs/concepts.md b/docs/docs/concepts.md index 8f87d4af..da3b1aee 100644 --- 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 index bcaf9a29..3c436545 100644 --- a/docs/docs/extra.css +++ b/docs/docs/extra.css @@ -1,3 +1,10 @@ .md-header__title { margin-left: 0 !important; -} \ No newline at end of file +} + +img { + margin-left: auto; + margin-right: auto; + max-width: 80% !important; +} + diff --git a/docs/docs/index.md b/docs/docs/index.md index 77161f3f..744c4879 100644 --- 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 index 1d666ac5..6381c2bd 100644 --- 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. \ No newline at end of file diff --git a/docs/docs/programmatic-api.md b/docs/docs/programmatic-api.md index e5d10f01..38fd1773 100644 --- a/docs/docs/programmatic-api.md +++ b/docs/docs/programmatic-api.md @@ -13,7 +13,7 @@ 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 @@ -21,7 +21,7 @@ If your framework does not already provide a configured `Stork` instance, you ne 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 index 1d3ba867..ae3be737 100644 --- 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 index 3d542bb8..ee529b87 100644 --- 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 index 983f2585..3510fa57 100644 --- 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 index 170f3819..50f3477c 100644 --- 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 index 7f867b78..3ef7437a 100644 --- 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 index aa4a4512..5456f244 100644 --- 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 index c87045d5..5467883c 100644 --- 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()));