Update web site

- update mkdocs - use themes (dark vs. light) - update images and diagrams to render correctly based on the theme - move the mkdocs.yaml in the docs directory and restructure docs (like mutiny) - use pipenv and a Pipfile - intregrate docissimo macros
smallrye · Jul 22, 2022 · c8de1a2 · c8de1a2
1 parent d9387a6
commit c8de1a2
Show file tree

Hide file tree

Showing 42 changed files with 763 additions and 88 deletions.
diff --git a/.github/render-documentation.sh b/.github/render-documentation.sh
@@ -5,6 +5,6 @@ DIR="$(dirname $(realpath "$0"))"
 echo $DIR
 
 export STORK_VERSION=$(cat "$DIR/project.yml" | yq eval '.release.current-version' -)
-
+cd docs
 mike deploy --push --update-aliases $STORK_VERSION latest --branch gh-pages
 mike set-default --push latest
diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml
@@ -28,11 +28,10 @@ jobs:
         run: |
           git config --global user.name "SmallRye CI"
           git config --global user.email "[email protected]"
+          cd docs
           sudo snap install yq
-          pip install mkdocs-material
-          pip install mkdocs-macros-plugin
-          pip install mkdocs-build-plantuml-plugin
-          pip install mike          
+          pip install
+          cd ..
       - name: Build local artifacts
         run: mvn -B install -DskipTests
       - name: Render docs and publish

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -56,39 +56,42 @@ Wait for a bit, and you're done.
 
 ## Building the documentation
 
-The documentation is built using [MKDoc](https://www.mkdocs.org/). 
+The documentation is built using [MKDoc](https://www.mkdocs.org/) and it stored in the `docs` directory
 
 ### Prerequisites
 
-You need Python 3 installed on your machine, with the following modules:
+You need Python 3 installed on your machine, as well as _pipenv_:
 
 ```shell
-pip3 install mkdocs
-pip3 install mkdocs-material
-pip3 install mkdocs-macros-plugin
-pip3 install mkdocs-build-plantuml-plugin
-pip3 install mike    
+# From the `docs` directory
+pip3 install pipenv # if you don't have it yet
+pipenv install
 ```
 
 ### Structure
 
-The website configuration is in the `mkdocs.yml` file. 
+The website configuration is in the `docs/mkdocs.yml` file. 
 The content is in the `docs` module.
 
 ### Build
 
-You can build the web site using, from the project root:
+You can build the web site using, from the `docs` module:
 
 ```shell
-mkdocs build
+pipenv run mkdocs build
 ```
 
 The website is generated in the `site` directory.
+You can also enable the _serve_ mode, which update the website while you update it:
 
-You can also enable the _serve_ mode, which update the web site while you update it:
+```shell
+pipenv run mkdocs serve
+```
+
+### Upgrade the dependencies
 
 ```shell
-mkdocs serve
+pipenv update
 ```
 
 ### Deployment

diff --git a/docs/Pipfile b/docs/Pipfile
@@ -0,0 +1,16 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+mkdocs = "*"
+mkdocs-material = "*"
+mkdocs-macros-plugin = "*"
+mkdocs-build-plantuml-plugin = "*"
+mike = "*"
+
+[dev-packages]
+
+[requires]
+python_version = "3"
diff --git a/docs/Pipfile.lock b/docs/Pipfile.lock
diff --git a/docs/concepts.md → docs/docs/concepts.md b/docs/concepts.md → docs/docs/concepts.md
@@ -4,7 +4,9 @@ This page presents the concepts used in Stork.
 When using Stork in a _managed_ environment, such as Quarkus, all these concepts are hidden, as you only configure the lookup and selection.
 However, when using the programmatic API, you will use these concepts directly.
 
-![concepts](target/stork.png)
+
+![concepts](target/stork.svg#only-light)
+![concepts](target/stork_dark.svg#only-dark)
 
 ## Process overview
 
@@ -14,7 +16,8 @@ When using the programmatic API of Stork, you can:
 2. Retrieve the `Service` you want to use. Each `Service` is associated with a name.
 3. Retrieve the `ServiceInstance` which will provide the metadata to access the actual service.
 
-![concepts](target/sequence.png)
+![service discovery and selection](target/sequence.svg#only-light)
+![service discovery and selection](target/sequence_dark.svg#only-dark)
 
 Behind the scenes, Stork will handle the service lookup and selection.
 
@@ -30,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<-- "docs/snippets/examples/StorkEntryPointExample.java"
+--8<-- "snippets/examples/StorkEntryPointExample.java"
 ```
 
 During the initialization, Stork looks for `io.smallrye.stork.config.ConfigProvider` SPI provider and retrieves the list of managed services:
@@ -46,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<-- "docs/snippets/examples/StorkServiceExample.java"
+--8<-- "snippets/examples/StorkServiceExample.java"
 ```
 
 The `Service` lets you retrieve the list of `ServiceInstance`, or select a single one, when a load-balancer is configured.
@@ -57,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<-- "docs/snippets/examples/StorkServiceLookupExample.java"
+--8<-- "snippets/examples/StorkServiceLookupExample.java"
 ```
 
 The service selection is a two-steps process:
@@ -66,7 +69,7 @@ The service selection is a two-steps process:
 2. Service selection - using the load balancer
 
 ```java linenums="1"
---8<-- "docs/snippets/examples/StorkServiceSelectionExample.java"
+--8<-- "snippets/examples/StorkServiceSelectionExample.java"
 ```
 
 ## Service Discovery

diff --git a/docs/docs/diagrams/includes/themes/dark.puml b/docs/docs/diagrams/includes/themes/dark.puml
@@ -0,0 +1,10 @@
+!define BG_MAIN_COLOR      #1A618C
+!define BG_SECONDARY_COLOR #616768
+!define BG_PACKAGE_COLOR   #7a209f
+!define BORDER_COLOR       #EEEEEE
+!define FONT_COLOR         #EEEEEE
+!define ARROW_COLOR        #EEEEEE
+
+' include the general skinparams for both, light and dark
+' to overwrite with the given settings
+!include general.puml
diff --git a/docs/docs/diagrams/includes/themes/general.puml b/docs/docs/diagrams/includes/themes/general.puml
@@ -0,0 +1,98 @@
+!define BORDER_THICKNESS 3
+skinparam backgroundColor transparent
+
+skinparam classFontSize 30
+
+skinparam Padding 4
+skinparam RoundCorner 4
+skinparam Shadowing false
+
+skinparam Default {
+  FontColor FONT_COLOR
+  FontSize 30
+}
+
+skinparam class {
+    BackgroundColor BG_MAIN_COLOR
+    ArrowColor FONT_COLOR
+    BorderColor FONT_COLOR
+    FontSize 30
+}
+
+skinparam Arrow {
+  Color FONT_COLOR
+  FontColor FONT_COLOR
+  FontStyle Bold
+  FontSize 30
+}
+
+skinparam package {
+  FontColor FONT_COLOR
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+}
+skinparam node {
+  FontColor FONT_COLOR
+  BackgroundColor BG_PACKAGE_COLOR
+  BorderColor BORDER_COLOR
+}
+skinparam component {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+  Style uml2
+}
+
+skinparam database {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+
+skinparam cloud {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+
+skinparam collections {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam Control {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam Boundary {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam Entity {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam interface {
+  BackgroundColor BG_MAIN_COLOR
+  BorderColor BORDER_COLOR
+  FontColor FONT_COLOR
+}
+skinparam SequenceParticipantBorderThickness 3
+skinparam sequence {
+  ParticipantBackgroundColor BG_MAIN_COLOR
+  ParticipantBorderColor BORDER_COLOR
+  ParticipantFontStyle normal
+  ParticipantFontColor FONT_COLOR
+  LifeLineBorderColor BORDER_COLOR
+  LifeLineBackgroundColor BG_MAIN_COLOR
+  ArrowColor FONT_COLOR
+  ArrowBorderColor BORDER_COLOR
+  ArrowFontColor FONT_COLOR
+  ArrowThickness 3
+  ActorBackgroundColor BG_MAIN_COLOR
+  ActorBorderColor BORDER_COLOR
+  ActorFontColor FONT_COLOR
+}
diff --git a/docs/docs/diagrams/includes/themes/light.puml b/docs/docs/diagrams/includes/themes/light.puml
@@ -0,0 +1,11 @@
+!define BG_MAIN_COLOR      AliceBlue
+!define BG_SECONDARY_COLOR #B4BCBE
+!define BG_PACKAGE_COLOR   #eeb291
+!define BORDER_COLOR       #444444
+!define FONT_COLOR         #444444
+!define ARROW_COLOR        DarkGrey
+
+
+' include the general skinparams for both, light and dark
+' to overwrite with the given settings
+!include general.puml
diff --git a/docs/diagrams/sequence.puml → docs/docs/diagrams/sequence.puml b/docs/diagrams/sequence.puml → docs/docs/diagrams/sequence.puml
@@ -1,19 +1,7 @@
 @startuml
-skinparam participant {
-    BackgroundColor AliceBlue
-    ArrowColor DarkGrey
-    BorderColor DarkGrey
-}
 
-skinparam roundcorner 20
+!include diagrams/includes/themes/light.puml
 
-skinparam sequence {
-    ArrowColor DarkGrey
-    ActorBorderColor DarkGrey
-    LifeLineBorderColor DarkGrey
-    LifeLineBackgroundColor #A9DCDF
-
-}
 skinparam sequenceMessageAlign center
 autonumber "<b>(0)"
 

diff --git a/docs/diagrams/srv_sequence.puml → docs/docs/diagrams/srv_sequence.puml b/docs/diagrams/srv_sequence.puml → docs/docs/diagrams/srv_sequence.puml
@@ -1,19 +1,6 @@
 @startuml
-skinparam participant {
-    BackgroundColor AliceBlue
-    ArrowColor DarkGrey
-    BorderColor DarkGrey
-}
+!include diagrams/includes/themes/light.puml
 
-skinparam roundcorner 20
-
-skinparam sequence {
-    ArrowColor DarkGrey
-    ActorBorderColor DarkGrey
-    LifeLineBorderColor DarkGrey
-    LifeLineBackgroundColor #A9DCDF
-
-}
 skinparam sequenceMessageAlign center
 
 

diff --git a/docs/diagrams/stork.puml → docs/docs/diagrams/stork.puml b/docs/diagrams/stork.puml → docs/docs/diagrams/stork.puml
@@ -1,27 +1,20 @@
 @startuml
-skinparam class {
-    BackgroundColor AliceBlue
-    ArrowColor DarkGrey
-    BorderColor DarkGrey
-}
+!include diagrams/includes/themes/light.puml
 hide members
-class Stork <<entry-point>> #line.bold;line:CornflowerBlue
+class Stork <<entry-point>>
 interface ServiceDiscovery
-interface ServiceInstance #line.bold;line:CornflowerBlue
+interface ServiceInstance
 interface LoadBalancer
-interface ConfigProvider <<SPI>>
-class Service <<named>> #line.bold;line:CornflowerBlue
+class Service <<named>>
 
-Stork --[dotted] ConfigProvider
 Stork -- "*" Service
 Service -- ServiceDiscovery
-Service -- "0..1" LoadBalancer
+Service -- LoadBalancer
 
 Service --[dotted] ServiceInstance: selectServiceInstance
 
 class Kubernetes implements ServiceDiscovery
 class Consul implements ServiceDiscovery
-class Static implements ServiceDiscovery
 class "Custom Service Discovery" implements ServiceDiscovery
 
 class RoundRobin<<default>> implements LoadBalancer

diff --git a/docs/extra.css → docs/docs/extra.css b/docs/extra.css → docs/docs/extra.css
diff --git a/docs/docs/images/problem-dark.png b/docs/docs/images/problem-dark.png
diff --git a/docs/docs/images/problem-light.png b/docs/docs/images/problem-light.png
diff --git a/docs/images/redhat_reversed.svg → docs/docs/images/redhat_reversed.svg b/docs/images/redhat_reversed.svg → docs/docs/images/redhat_reversed.svg
diff --git a/docs/docs/images/solution-dark.png b/docs/docs/images/solution-dark.png
diff --git a/docs/docs/images/solution-light.png b/docs/docs/images/solution-light.png
diff --git a/docs/images/stork-white.png → docs/docs/images/stork-white.png b/docs/images/stork-white.png → docs/docs/images/stork-white.png
diff --git a/docs/index.md → docs/docs/index.md b/docs/index.md → docs/docs/index.md
@@ -24,14 +24,16 @@ 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.png)
+![the problem](images/problem-light.png#only-light)
+![the problem](images/problem-dark.png#only-dark)
 
 ## The solution
 
 Stork handles the service lookup and selection.
 It proposes an extensible set of service discovery mechanisms and load-balancing strategies.
 
-![the solution](images/solution.png)
+![the solution](images/solution-light.png#only-light)
+![the solution](images/solution-dark.png#only-dark)
 
 ## What if the infrastructure provides such a feature?
 

diff --git a/docs/load-balancer/custom-load-balancer.md → ...ocs/load-balancer/custom-load-balancer.md b/docs/load-balancer/custom-load-balancer.md → ...ocs/load-balancer/custom-load-balancer.md
@@ -49,7 +49,7 @@ Any configuration properties that the provider expects should be defined with `@
 
 A load balancer provider class should look as follows:
 ```java linenums="1"
---8<-- "docs/snippets/examples/AcmeLoadBalancerProvider.java"
+--8<-- "snippets/examples/AcmeLoadBalancerProvider.java"
 ```
 
 Note, that the `LoadBalancerProvider` interface takes a configuration class as a parameter. 
@@ -61,7 +61,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<-- "docs/snippets/examples/AcmeLoadBalancer.java"
+--8<-- "snippets/examples/AcmeLoadBalancer.java"
 ```
 
 This implementation is simplistic and just picks a random instance from the received list.
@@ -98,7 +98,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<-- "docs/snippets/examples/AcmeSelectorApiUsage.java"
+--8<-- "snippets/examples/AcmeSelectorApiUsage.java"
 ```
 
 Remember that attributes, like `my-attribute`, are declared using the `@LoadBalancerAttribute` annotation on the `LoadBalancerProvider` implementation.
diff --git a/docs/load-balancer/least-requests.md → docs/docs/load-balancer/least-requests.md b/docs/load-balancer/least-requests.md → docs/docs/load-balancer/least-requests.md
diff --git a/docs/load-balancer/power-of-two-choices.md → ...ocs/load-balancer/power-of-two-choices.md b/docs/load-balancer/power-of-two-choices.md → ...ocs/load-balancer/power-of-two-choices.md
diff --git a/docs/load-balancer/random.md → docs/docs/load-balancer/random.md b/docs/load-balancer/random.md → docs/docs/load-balancer/random.md
diff --git a/docs/load-balancer/response-time.md → docs/docs/load-balancer/response-time.md b/docs/load-balancer/response-time.md → docs/docs/load-balancer/response-time.md
diff --git a/docs/load-balancer/round-robin.md → docs/docs/load-balancer/round-robin.md b/docs/load-balancer/round-robin.md → docs/docs/load-balancer/round-robin.md
diff --git a/docs/load-balancer/sticky.md → docs/docs/load-balancer/sticky.md b/docs/load-balancer/sticky.md → docs/docs/load-balancer/sticky.md