Migration of the documentation and website to MkDocs (#980)

* Migration of the documentation and website to MkDocs

* Set the Git icon to GitHub

.build/UpdateDocsAttributesFiles.java

@@ -0,0 +1,56 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+//DEPS org.kohsuke:github-api:1.307
+//DEPS info.picocli:picocli:4.6.3
+
+import org.kohsuke.github.GitHub;
+import org.kohsuke.github.GitHubBuilder;
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.concurrent.Callable;
+
+@Command(name = "UpdateDocsAttributesFiles", mixinStandardHelpOptions = true, description = "Update the documentation attributes file")
+public class UpdateDocsAttributesFiles implements Callable<Integer> {
+
+    @Option(names = "--mutiny-version", description = "Pass a Mutiny version instead of fetching it from GitHub")
+    String mutinyVersion;
+
+    @Option(names = "--vertx-bindings-version", description = "Pass a Vert.x bindings version instead of fetching it from GitHub")
+    String vertxBindingsVersion;
+
+    @Override
+    public Integer call() throws Exception {
+        var gh = new GitHubBuilder().build();
+        var lastMutinyRelease = (mutinyVersion == null) ? getRelease(gh, "smallrye/smallrye-mutiny") : mutinyVersion;
+        var lastBindingsRelease = (vertxBindingsVersion == null) ? getRelease(gh, "smallrye/smallrye-mutiny-vertx-bindings") : vertxBindingsVersion;
+
+        // Use multiline blocks when Java 17 will be the baseline
+        var indent = "    ";
+        var newline = "\n";
+        var builder = new StringBuilder();
+        builder
+                .append("# GENERATED FILE, DO NOT EDIT DIRECTLY (see .build/UpdateDocsAttributesFiles.java)").append(newline)
+                .append("attributes:").append(newline)
+                .append(indent).append("project-version: ").append(lastMutinyRelease).append(newline)
+                .append(indent).append("versions:").append(newline)
+                .append(indent).append(indent).append("mutiny: ").append(lastMutinyRelease).append(newline)
+                .append(indent).append(indent).append("vertx_bindings: ").append(lastBindingsRelease).append(newline);
+
+        Files.writeString(Path.of("documentation/attributes.yaml"), builder.toString(), StandardCharsets.UTF_8);
+        return 0;
+    }
+
+    private String getRelease(GitHub gh, String name) throws IOException {
+        return gh.getRepository(name).getLatestRelease().getName();
+    }
+
+    public static void main(String... args) {
+        var status = new CommandLine(new UpdateDocsAttributesFiles()).execute(args);
+        System.exit(status);
+    }
+}

.build/cut-release.sh

@@ -42,11 +42,15 @@ else
 fi
 
 echo "Update website version to ${VERSION}"
-sed -ie "s/mutiny_version: .*/mutiny_version: ${VERSION}/g" documentation/src/main/jekyll/_data/versions.yml
-rm -f documentation/src/main/jekyll/_data/versions.ymle
-git add documentation/src/main/jekyll/_data/versions.yml
-git commit -m "Bumping the website version to ${VERSION}"
-git push
+.build/UpdateDocsAttributesFiles.java --mutiny-version=${VERSION}
+if [[ $(git diff --stat) != '' ]]; then
+    git add documentation/attributes.yaml
+    git commit -m "Bumping the website version to ${VERSION}"
+    git push
+    echo "Version updated"
+else
+  echo "The version was already correct"
+fi
 
 echo "Cutting release ${VERSION}"
 ./mvnw -s .build/maven-ci-settings.xml -B -fn clean

.build/deploy-site.sh

@@ -1,21 +1,14 @@
-#!/usr/bin/env bash
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
 echo "🚧 Building..."
-cd documentation || exit 1
-cd src/main/jekyll && gem install bundler && bundle install && JEKYLL_ENV=production bundle exec jekyll build  && cd - || exit 1
-echo "🍺 Site generated in 'target/_site'"
 
-echo "🚧 Cloning web site in target/site"
-cd target || exit
-git clone -b gh-pages "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/smallrye/smallrye-mutiny.git" site
-echo "🚧 Copy content"
-# shellcheck disable=SC2216
-rm -rf site/*
-cp -R _site/* site
-echo "🚧 Pushing documentation"
-cd site || exit
-git add -A
-git commit -m "update site"
-git push origin gh-pages
-echo "🍺 Site updated!"
-cd ../../..
+cd documentation
+PROJECT_VERSION=$(yq '.attributes.versions.mutiny' attributes.yaml)
 
+pipenv shell
+mike deploy --push --update-aliases $PROJECT_VERSION latest
+mike set-default --push latest
+
+echo "🍺 Site updated!"

.github/workflows/deploy-site.yml

@@ -15,24 +15,32 @@ jobs:
         with:
           ref: ${{ github.event.ref }}
           token: ${{ secrets.RELEASE_TOKEN }}
-      - name: Install JDK 11
+          fetch-depth: 0 # fetch all commits and branches for mike to work properly
+      - name: 'Install JDK 11'
         uses: actions/setup-java@v2
         with:
           java-version: 11
           distribution: temurin
           cache: maven
-      - name: 'Setup Ruby'
-        uses: ruby/setup-ruby@v1
+      - name: 'Setup yq (portable yaml processor)'
+        uses: mikefarah/yq@master
+      - name: 'Setup Python'
+        uses: actions/setup-python@v4
         with:
-          ruby-version: '2.6'
+          python-version: 3.x
+      - name: 'Install Python packages'
+        run: |
+          cd documentation
+          pip install pipenv
+          pipenv install
       - name: 'Web Site'
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
           GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
           REF: ${{ github.event.ref }}
           SECRET_FILES_PASSPHRASE: ${{ secrets.SECRET_FILES_PASSPHRASE }}
         run: |
-          MUTINY_VERSION=$(cat documentation/src/main/jekyll/_data/versions.yml | grep mutiny_version | awk '{print $2}')
+          MUTINY_VERSION=$(yq '.attributes.versions.mutiny' documentation/attributes.yaml)
           echo "Deploying web site for Mutiny ${MUTINY_VERSION}"
 
           sudo apt-get update -o Dir::Etc::sourcelist="sources.list" \
@@ -48,7 +56,7 @@ jobs:
 
           echo "Waiting for artifacts to be available from Maven Central"
           jbang .build/WaitForCentral.java \
-            --artifacts=io.smallrye.reactive:mutiny,io.smallrye.reactive:mutiny-smallrye-context-propagation,io.smallrye.reactive:mutiny-test-utils,io.smallrye.reactive:mutiny-kotlin,io.smallrye.reactive:mutiny-reactor,io.smallrye.reactive:mutiny-rxjava \
+            --artifacts=$(./mvnw -Dexec.executable='echo' -Dexec.args='${project.groupId}:${project.artifactId}' exec:exec -q | tr '\n' ',') \
             --expected-version="${MUTINY_VERSION}"
 
           echo "Run the deployment script"

.github/workflows/post-release.yml

@@ -58,7 +58,7 @@ jobs:
           TAG=$(echo ${REF} | sed -e 's%refs/tags/%%g')
           echo "Waiting for artifacts to be available from Maven Central, otherwise the build will fail during the compatibility verification"
           jbang .build/WaitForCentral.java \
-            --artifacts=io.smallrye.reactive:mutiny,io.smallrye.reactive:mutiny-smallrye-context-propagation,io.smallrye.reactive:mutiny-test-utils,io.smallrye.reactive:mutiny-kotlin,io.smallrye.reactive:mutiny-reactor,io.smallrye.reactive:mutiny-rxjava \
+            --artifacts=$(./mvnw -Dexec.executable='echo' -Dexec.args='${project.groupId}:${project.artifactId}' exec:exec -q | tr '\n' ',') \
             --expected-version="${TAG}"
 
           git clone -b main "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/smallrye/smallrye-mutiny.git" new-main

README.md

@@ -0,0 +1,83 @@
+![Build Status](https://github.com/smallrye/smallrye-mutiny/actions/workflows/build-main.yml/badge.svg) 
+![Build status (1.x branch)](https://github.com/smallrye/smallrye-mutiny/actions/workflows/build-1.x.yml/badge.svg) 
+![License](https://img.shields.io/github/license/smallrye/smallrye-mutiny.svg) 
+![Maven Central](https://img.shields.io/maven-central/v/io.smallrye.reactive/mutiny?color=green) 
+![Javadoc](https://javadoc.io/badge2/io.smallrye.reactive/mutiny/javadoc.svg)
+
+# ⚡️ Mutiny, an Intuitive Event-Driven Reactive Programming Library for Java
+
+[Mutiny is a novel reactive programming library](https://smallrye.io/smallrye-mutiny/).
+
+Mutiny provides a simple but powerful asynchronous development model that lets you build reactive applications.
+
+## 🚀 Overview
+
+Mutiny can be used in any Java application exhibiting asynchrony.
+
+From reactive microservices, data streaming, event processing to API gateways and network utilities, Mutiny is a great fit.
+
+### Event-Driven
+
+Mutiny places events at the core of its design. 
+With Mutiny, you observe events, react to them, and create elegant and readable processing pipelines.
+
+**💡 A PhD in functional programming is not required.**
+
+### Navigable
+
+Even with smart code completion, classes with hundred of methods are confusing.
+
+Mutiny provides a navigable and explicit API driving you towards the operator you need.
+
+### Non-Blocking I/O
+
+Mutiny is the perfect companion to tame the asynchronous nature of applications with non-blocking I/O.
+
+Declaratively compose operations, transform data, enforce progress, recover from failures and more.
+
+### Quarkus and Vert.x native
+
+Mutiny is integrated in [Quarkus](https://quarkus.io) where every reactive API uses Mutiny, and [Eclipse Vert.x](https://vertx.io) clients are made available using [Mutiny bindings](https://github.com/smallrye/smallrye-mutiny-vertx-bindings).
+
+Mutiny is however an independent library that can ultimately be used in any Java application.
+
+### Reactive Converters Built-In
+
+Mutiny is based on the [Reactive Streams specification](https://www.reactive-streams.org/), and so it can be integrated with any other reactive programming library.
+
+In addition, Mutiny offers converters to interact with other popular libraries and [Kotlin](https://kotlinlang.org/).
+
+## 📦 Build instructions
+
+Mutiny is built with Apache Maven, so all you need is:
+
+```shell
+./mvnw install
+```
+
+| Git branch | Versions                       | Baseline                        | Compliance                 |
+|------------|--------------------------------|---------------------------------|----------------------------|
+| `main`     | 2.x *(in development)*         | Java 11, Reactive Streams 1.0.4 | Reactive Streams TCK 1.0.4 |
+| `1.x`      | 1.6.x *(backports, bug fixes)* | Java 8, Reactive Streams 1.0.4  | Reactive Streams TCK 1.0.4 |
+
+## ✨ Contributing
+
+See [the contributing guidelines](CONTRIBUTING.md)
+
+Mutiny is an open project, feel-free to:
+
+- [report issues](https://github.com/smallrye/smallrye-mutiny/issues), and
+- [propose enhancements via pull-requests](https://github.com/smallrye/smallrye-mutiny/pulls).
+
+## 👋 Discussions and support
+
+For anything related to the usage of Mutiny in Quarkus, please refer to the [Quarkus support](https://quarkus.io/support/)
+
+For more general discussions about Mutiny, you can:
+
+- [start a new discussion thread in GitHub Discussions (preferred option)](https://github.com/smallrye/smallrye-mutiny/discussions), or
+- [use the `mutiny` tag on StackOverflow](https://stackoverflow.com/questions/tagged/mutiny).
+
+## 🧪 Publications
+
+Julien Ponge, Arthur Navarro, Clément Escoffier, and Frédéric Le Mouël. 2021. **[Analysing the Performance and Costs of Reactive Programming Libraries in Java](https://doi.org/10.1145/3486605.3486788).** *In Proceedings of the 8th ACM SIGPLAN International Workshop on Reactive and Event-Based Languages and Systems (REBLS ’21)*, October 18, 2021, Chicago, IL, USA. ACM, New York, NY, USA, 10 pages. [(PDF)](https://hal.inria.fr/hal-03409277/document)

documentation/Pipfile

@@ -0,0 +1,15 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+mkdocs = "==1.3.0"
+mkdocs-material = "==8.3.4"
+mkdocs-macros-plugin = "==0.7.0"
+mike = "==1.1.2"
+
+[dev-packages]
+
+[requires]
+python_version = "3.10"