Deduplicate documentation (#255)

* deduplicate documentation * changes from review * upload docs and jar-with-dependencies to gh release
codecentric · Jul 30, 2021 · 041a120 · 041a120
1 parent b5f75d1
commit 041a120
Show file tree

Hide file tree

Showing 14 changed files with 101 additions and 73 deletions.
diff --git a/.github/workflows/releasetag.yml b/.github/workflows/releasetag.yml
@@ -26,18 +26,23 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-maven-
       - name: Run Maven deploy
-        run: ./mvnw deploy -DperformRelease=true --settings .settings.xml
+        run: ./mvnw deploy -DperformRelease=true --settings .settings.xml -pl chaos-monkey-spring-boot
         env:
           SONATYPE_USERTOKEN: ${{ secrets.SONATYPE_USERTOKEN }}
           SONATYPE_USERTOKENPASSWORD: ${{ secrets.SONATYPE_USERTOKENPASSWORD }}
           GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+      - name: Gather docs
+        run: |
+          mkdir ./docs/latest
+          cp -R ./chaos-monkey-docs/target/generated-docs ./docs/latest/
+          cp README.md ./docs/
+          sed -i 's/docs\/images/images/g' ./docs/README.md
       - name: Publish gh-pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           enable_jekyll: true
-          publish_dir: ./chaos-monkey-docs/target/generated-docs
-          destination_dir: latest
+          publish_dir: ./docs
           commit_message: ${{ github.event.head_commit.message }}
 
   create_github_release:
@@ -62,15 +67,20 @@ jobs:
           key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
           restore-keys: |
             ${{ runner.os }}-maven-
-      - name: Convert changelog to docbook
-        run: ./mvnw asciidoctor:process-asciidoc@output-docbook -pl chaos-monkey-docs
+      - name: Generate documentation (docbook, html, zip)
+        run: ./mvnw asciidoctor:process-asciidoc@output-docbook generate-resources -pl chaos-monkey-docs
       - name: Convert changelog from docbook to markdown
         uses: docker://pandoc/core:2.14
         with:
           args: "-f docbook -t gfm -o changes.md chaos-monkey-docs/target/generated-docbook/changes.xml --wrap=none"
+      - name: Generate jar with dependencies
+        run: ./mvnw package -pl chaos-monkey-spring-boot
       - name: Create Github Release
         uses: softprops/action-gh-release@v1
         with:
           body_path: changes.md
+          files: |
+            ./chaos-monkey-docs/target/chaos-monkey-docs-*.zip
+            ./chaos-monkey-spring-boot/target/chaos-monkey-spring-boot-*-jar-with-dependencies.jar
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-[![Apache License 2](https://img.shields.io/badge/license-ASF2-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.txt)
+[![Apache License 2](https://img.shields.io/github/license/codecentric/chaos-monkey-spring-boot)](https://www.apache.org/licenses/LICENSE-2.0.txt)
 [![Build Status](https://github.com/codecentric/chaos-monkey-spring-boot/workflows/Chaos%20Monkey%20Build/badge.svg)](https://github.com/codecentric/chaos-monkey-spring-boot/actions?query=workflow%3A%22Chaos+Monkey+Build%22)
 [![codecov](https://codecov.io/gh/codecentric/chaos-monkey-spring-boot/branch/main/graph/badge.svg)](https://codecov.io/gh/codecentric/chaos-monkey-spring-boot)
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/de.codecentric/chaos-monkey-spring-boot/badge.svg)](https://maven-badges.herokuapp.com/maven-central/de.codecentric/chaos-monkey-spring-boot/)
@@ -13,10 +13,10 @@
 
 This project provides a Chaos Monkey for Spring Boot applications and will try to attack your running Spring Boot App.
 
->All details are explained on [Chaos Monkey for Spring Boot](https://codecentric.github.io/chaos-monkey-spring-boot/)
+>Everything from getting started to advanced usage is explained in the [Documentation for Chaos Monkey for Spring Boot](https://codecentric.github.io/chaos-monkey-spring-boot/latest/) 
 
 ## Introduction
-If you're not familiar with the principles of chaos engineering yet, check out my latest blog post and enter the world of chaos engineering.
+If you're not familiar with the principles of chaos engineering yet, check out this blog post and enter the world of chaos engineering.
 
 <a href="https://blog.codecentric.de/en/2018/07/chaos-engineering/" target="_blank"><img src="https://pbs.twimg.com/media/DhaRNO7XUAAi00i.jpg" 
 alt="Chaos Engineering – withstanding turbulent conditions in production" width="260" height="155" border="10" /></a><br>
@@ -25,20 +25,60 @@ Get familiar with the Chaos Monkey for Spring Boot in the following video, <a hr
 
 <a href="https://goo.gl/r2Tmig" target="_blank"><img src="https://i.ytimg.com/vi/7sQiIR9qCdA/maxresdefault.jpg" 
 alt="Chaos Monkey for Spring Boot" width="260" height="155" border="10" /></a><br>
-**Chaos Monkey for Spring Boot - new features**
 
-## Contributions 
-Chaos Monkey is open source and welcomes contributions from everyone. The <a href="https://github.com/codecentric/chaos-monkey-spring-boot/blob/main/CONTRIBUTING.adoc" target="_blank">contribution-guideline</a> is where you should begin in order to best understand how to contribute to this project. 
+## What is the goal of Chaos Monkey?
+
+Inspired by [PRINCIPLES OF CHAOS ENGINEERING](https://principlesofchaos.org/), with a focus on [Spring Boot](https://projects.spring.io/spring-boot/), Chaos Monkey wants to test applications better and especially during operation.
+
+After writing many unit and integration tests, a code coverage from 70% to 80%, this unpleasant feeling remains, how our baby behaves in production?
+
+Many questions remain unanswered:
+
+- Will our fallbacks work?
+- How does the application behave with network latency?
+- What if one of our services breaks down?
+- Service Discovery works, but is our Client-Side-Load-Balancing also working?
+
+As you can see, there are many more questions and open topics you have to deal with.
 
+That was the start of Chaos Monkey for Spring Boot.
+
+### How does it work?
+If Spring Boot Chaos Monkey is on your classpath and activated with profile name `chaos-monkey`, it will automatically hook into your application. 
+
+Now you can activate [watchers](https://codecentric.github.io/chaos-monkey-spring-boot/latest/#watchers), which look for classes to [assault](https://codecentric.github.io/chaos-monkey-spring-boot/latest/#assaults). There are also [runtime assaults](https://codecentric.github.io/chaos-monkey-spring-boot/latest/#runtime-assaults), which attack your whole application.
+
+<p align="center">
+  <img class="imgborder s1" width="90%" src="docs/images/sb-chaos-monkey-architecture.png">
+</p>
+
+## Be social and communicative!
+If you start to implement Chaos Engineering at your company, then you must be a very social and communicative person. Why? Because you will get to know many of your colleagues personally in a very short time when your chaos experiments strike.
+
+### Check your resilience
+Are your services already resilient and can handle failures? Don´t start a chaos experiment if not!
+
+### Implement active application monitoring
+Check your monitoring and check if you can see the overall state of your system. There are many great tools out there to get a pleasant feeling about your entire system.
+
+### Define steady states
+Define a metric to check a steady state of your service and of course your entire system. Start small with a service that is not critical.
+
+### Do not start in production
+Of course, you can start in production, but keep in mind...
+
+> The best place on earth is...production!<br>
+> *Josh Long*
+
+...so let's keep production as the best place on earth and look for our first experiences on another stage. If all goes well, and you're confident, run it in production.
 
 ## Documentation
-[Documentation](https://codecentric.github.io/chaos-monkey-spring-boot/#docs)
+[Documentation](https://codecentric.github.io/chaos-monkey-spring-boot/latest/)
 
-## Releases
-[Releases](https://codecentric.github.io/chaos-monkey-spring-boot/#releases)
+## Contributions 
+Chaos Monkey is open source and welcomes contributions from everyone. The [contribution guideline](https://github.com/codecentric/chaos-monkey-spring-boot/blob/main/CONTRIBUTING.adoc) is where you should begin in order to best understand how to contribute to this project. 
 
->Chaos Monkey for Spring Boot 1.0.1 depends on [Spring Boot 2.0.x](https://projects.spring.io/spring-boot/) and [Spring Framework 5.0.x](https://projects.spring.io/spring-framework/)
 
 
-## Latest Snapshots
-[Snapshots](https://codecentric.github.io/chaos-monkey-spring-boot/#snapshots)
+## Releases
+[Releases](https://github.com/codecentric/chaos-monkey-spring-boot/releases)
diff --git a/chaos-monkey-docs/pom.xml b/chaos-monkey-docs/pom.xml
@@ -44,6 +44,7 @@
                         <phase>generate-resources</phase>
                         <goals>
                             <goal>process-asciidoc</goal>
+                            <goal>zip</goal>
                         </goals>
                         <configuration>
                             <sourceDocumentName>index.adoc</sourceDocumentName>

diff --git a/chaos-monkey-docs/src/main/asciidoc/assaults.adoc b/chaos-monkey-docs/src/main/asciidoc/assaults.adoc
@@ -18,6 +18,7 @@ You can determine at runtime whether an exception should occur when the method i
 
 Thanks to the great community, the Chaos Monkey for Spring Boot can throw any kind of RuntimeException. You can configure the required exception at runtime via the Actuator Endpoint.
 
+[[runtime-assaults]]
 === Runtime Assaults ===
 
 These assaults attack your whole application.

diff --git a/chaos-monkey-docs/src/main/asciidoc/getting-started.adoc b/chaos-monkey-docs/src/main/asciidoc/getting-started.adoc
@@ -18,6 +18,8 @@ There are two ways to integrate the Chaos Monkey for Spring Boot into your exist
 </dependency>
 ----
 
+NOTE: If you want to use the latest snapshot version, add the sonatype staging repository `https://oss.sonatype.org/content/repositories/snapshots/`
+
 2.) Start your Spring Boot App Command-Line example:
 
 [source,txt,subs="verbatim,attributes"]

diff --git a/chaos-monkey-docs/src/main/asciidoc/index.adoc b/chaos-monkey-docs/src/main/asciidoc/index.adoc
@@ -1,5 +1,4 @@
 = Chaos Monkey for Spring Boot Reference Guide =
-Benjamin Wilms <https://twitter.com/mrbwilms[@MrBWilms]>
 :revnumber: {project-version}
 :revdate: {commit-time}
 :toc: left
@@ -13,25 +12,6 @@ Benjamin Wilms <https://twitter.com/mrbwilms[@MrBWilms]>
 :last-update-label!:
 :tabsize: 2
 
-== What is the goal of Chaos Monkey? ==
-
-Inspired by http://principlesofchaos.org/[PRINCIPLES OF CHAOS ENGINEERING] and by my work in distributed system, with a focus on http://projects.spring.io/spring-boot/[Spring Boot], I wanted to test the resulting applications better and especially during operation.
-
-After writing many unit and integration tests, a code coverage from 70% to 80%, this unpleasant feeling remains, how our baby behaves in production?
-
-Many questions remain unanswered:
-
-- Will our fallbacks work?
-- How does the application behave with network latency?
-- What if one of our services breaks down?
-- Service Discovery works, but is our Client-Side-Load-Balancing also working?
-
-As you can see, there are many more questions and open topics you have to deal with.
-
-That was my start to take a deep dive into Chaos Engineering and I started this little project to share my thoughts and experience.
-
-A detailed explanation of when and why you should use the Chaos Monkey for Spring Boot https://codecentric.github.io/chaos-monkey-spring-boot/[can be found here].
-
 include::getting-started.adoc[]
 include::endpoints.adoc[]
 include::toggles.adoc[]

diff --git a/chaos-monkey-docs/src/main/asciidoc/watcher.adoc b/chaos-monkey-docs/src/main/asciidoc/watcher.adoc
@@ -1,4 +1,4 @@
-[[watcher]]
+[[watchers]]
 == Watcher ==
 A watcher is a Chaos Monkey for Spring Boot component, that will scan your app for a specific type of annotation.
 

diff --git a/demo-apps/chaos-monkey-demo-app-ext-jar/pom.xml b/demo-apps/chaos-monkey-demo-app-ext-jar/pom.xml
@@ -73,13 +73,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>
diff --git a/demo-apps/chaos-monkey-demo-app-naked/pom.xml b/demo-apps/chaos-monkey-demo-app-naked/pom.xml
@@ -85,13 +85,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>
diff --git a/demo-apps/chaos-monkey-demo-app-unleash-toggles/pom.xml b/demo-apps/chaos-monkey-demo-app-unleash-toggles/pom.xml
@@ -99,13 +99,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>
diff --git a/demo-apps/chaos-monkey-demo-app/pom.xml b/demo-apps/chaos-monkey-demo-app/pom.xml
@@ -94,13 +94,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>
diff --git a/demo-apps/chaos-monkey-web-reactive-app/pom.xml b/demo-apps/chaos-monkey-web-reactive-app/pom.xml
@@ -77,13 +77,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-deploy-plugin</artifactId>
-                <configuration>
-                    <skip>true</skip>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,9 @@
+theme: jekyll-theme-cayman
+title: Chaos Monkey for Spring Boot
+author: Codecentric
+description: This project provides a Chaos Monkey for Spring Boot and will try to attack your running Spring Boot App.
+social:
+  name: Codecentric
+  links:
+    - https://www.codecentric.de/
+    - https://github.com/codecentric
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
@@ -0,0 +1,20 @@
+---
+---
+
+@import "{{ site.theme }}";
+
+.main-content {
+  max-width: 90rem;
+}
+
+.imgborder {
+  display:inline-block;
+  position:relative;
+  border:1px solid #01add1;
+}
+
+.imgborder.s1 {
+  -webkit-box-shadow: 0 28px 16px -26px rgba(0, 0, 0, 0.5);
+  -moz-box-shadow: 0 28px 16px -26px rgba(0, 0, 0, 0.5);
+  box-shadow: 0 28px 16px -26px rgba(0, 0, 0, 0.5);
+}