Data driven documentation on implementations under test

.github/workflows/gh-pages.yml

@@ -0,0 +1,101 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches: [ main]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+
+# Allow one concurrent deployment, per branch
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  get_impls:
+    needs: build_pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Set up JDK
+        uses: actions/setup-java@0ab4596768b603586c0de567f2430c30f5b0d2b0 # v3.13.0
+        with:
+          java-version: '17'
+          distribution: 'adopt'
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@842c587ad8aa4c68eeba24c396e15af4c2e9f30a # v2.9.0
+        with:
+          gradle-home-cache-cleanup: true
+      - name: Run functional tests
+        run: | 
+          ./gradlew --quiet extractImplementations > implementations.json
+          cat implementations.json >> $GITHUB_STEP_SUMMARY
+      - name: Upload Implementations
+        uses: actions/upload-artifact@v3
+        with:
+          name: implementations
+          path: implementations.json
+          retention-days: 1
+
+  build_pages:
+    needs: get_impls
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/docs/Gemfile
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v3.4.0
+        with:
+          fetch-depth: 0 # need full history to get page last modified times
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@250fcd6a742febb1123a77a841497ccaa8b9e939 # v1.152.0
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@f156874f8191504dae5b037505266ed5dda6c382 # v3.0.6
+      - name: Download Implementations JSON
+        uses: actions/download-artifact@v3
+        with:
+          name: implementations
+      - name: Inject Implementations JSON into site
+        run: sed -i $'/IMPLEMENTATIONS_JSON/ { r implementations.json\nd }' "docs/_docs/1. implementations.md"
+      - name: Build with Jekyll
+        # Outputs to the './docs/_site' directory by default
+        run: (cd docs && bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}")
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@a753861a5debcf57bf8b404356158c8e1e33150c # v2.0.0
+        with:
+          path: "docs/_site/"
+
+  # Deployment job
+  deploy_pages:
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    needs: build_pages
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@9dbe3824824f8a1377b8e298bafde1a50ede43e5 # v2.0.4
+      - name: Ping Google Search
+        run: curl "https://www.google.com/ping?sitemap=https://www.creekservice.org/${{ github.event.repository.name }}/sitemap.xml"

build.gradle.kts

@@ -152,8 +152,13 @@ val runBenchmarkSmokeTest = tasks.register<JavaExec>("runBenchmarkSmokeTest") {
     dependsOn(pullTask)
 }
 
+val extractImplementations = tasks.register<JavaExec>("extractImplementations") {
+    classpath = sourceSets.main.get().runtimeClasspath
+    mainClass.set("org.creekservice.kafka.test.perf.ImplementationsMain")
+}
+
 tasks.check {
-    dependsOn(runFunctionalTests, runBenchmarkSmokeTest)
+    dependsOn(runFunctionalTests, runBenchmarkSmokeTest, extractImplementations)
 }
 
 // Dummy / empty tasks required to allow the repo to use the same standard GitHub workflows as other Creek repos:

docs/.gitignore

@@ -0,0 +1,15 @@
+# Apple
+**/.DS_Store
+
+# Ruby Gem
+*.gem
+.bundle
+Gemfile.lock
+**/vendor/bundle
+
+# Jekyll generated files
+.jekyll-cache
+.jekyll-metadata
+.sass-cache
+_asset_bundler_cache
+_site

docs/Gemfile

@@ -0,0 +1,23 @@
+# Copyright 2023 Creek Contributors (https://github.com/creek-service)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "creek-jekyll-theme", "~> 1.0"
+
+# # If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem 'jekyll-include_snippet', "~> 0.2"
+end

docs/README.md

@@ -0,0 +1,42 @@
+# Repos GitHub pages site.
+
+## Setup
+
+If you want to hack about with the site or add content, then follow these instructions to be able to run locally.
+
+### Prerequisites
+
+1. Install Git, obviously.
+2. [Install Jekyll](https://jekyllrb.com/docs/installation)
+3. Install [Builder](https://bundler.io/) by running `gem install bundler`.
+
+### Installing
+
+#### 1. Install the gems
+
+```shell
+(cd docs && bundle install)
+```
+
+#### 2. Update
+
+Occasionally update gems
+
+```shell
+git checkout main
+git pull
+(cd docs && bundle update)
+git checkout -b gems-update
+git add .
+git commit -m "updating gems"
+git push --set-upstream origin gems-update
+```
+
+#### 3. Run the local server
+
+```shell
+(cd docs && bundle exec jekyll serve --livereload --baseurl /json-schema-validation-comparison)
+```
+
+This will launch a web server so that you can work on the site locally.
+Check it out on [http://localhost:4000/json-schema-validation-comparison](http://localhost:4000/json-schema-validation-comparison).

docs/_config.dev.yml

@@ -0,0 +1,13 @@
+# Develop override settings
+
+url: http://localhost:4000
+
+analytics:
+  provider: false
+
+comments:
+  disqus:
+    shortname            : "creek-service-dev"
+
+sass:
+  style: expanded

docs/_config.yml

@@ -0,0 +1,52 @@
+
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your entire site, values
+# which you are expected to set up once and rarely need to edit after that.
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# `jekyll serve`. If you change this file, please restart the server process.
+
+# Site Settings
+theme      : "creek-jekyll-theme"
+baseurl    : "/json-schema-validation-comparison"
+repository : "creek-service/json-schema-validation-comparison"
+
+# Reading Files
+include:
+  - .htaccess
+  - _pages
+exclude:
+  - README.md
+
+# Collections
+collections:
+  docs:
+    output: true
+    permalink: /:collection/:path
+
+# Defaults
+defaults:
+  # _pages
+  - scope:
+      path: "_pages"
+      type: pages
+    values:
+      layout: single
+      author_profile: false
+      toc: true
+      toc_sticky: true
+      share: true
+  # _docs
+  - scope:
+      path: ""
+      type: docs
+    values:
+      layout: single
+      read_time: false
+      author_profile: false
+      share: false
+      comments: false
+      toc: false
+      toc_sticky: true
+      sidebar:
+        nav: "docs"

docs/_data/navigation/docs.yml

@@ -0,0 +1,10 @@
+- title: JSON Validator Comparison
+  children:
+    - title: Introduction
+      url: /
+    - title: Libraries under test
+      url: /implementations
+    - title: Functional comparison
+      url: /functional
+    - title: Performance comparison
+      url: /performance

docs/_docs/1. implementations.md

@@ -0,0 +1,48 @@
+---
+title: List of JSON Validator implementations under test
+permalink: /implementations
+layout: single
+header:
+  image: /assets/images/json.png
+toc: false
+classes: wide
+---
+
+See below for an up-to-date list of the JVM based JSON Validator implementations covered by this performance and functionality comparison.
+
+<div>
+ <table id="implsTable"></table>
+</div>
+
+[//]: # (Table scripts: https://github.com/fiduswriter/Simple-DataTables)
+<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/style.css" rel="stylesheet" type="text/css">
+<script src="https://cdn.jsdelivr.net/npm/[email protected]" type="text/javascript"></script>
+
+<script>
+    const implData = 
+      IMPLEMENTATIONS_JSON
+    ;
+
+    new simpleDatatables.DataTable("#implsTable", {
+        paging: false,
+        searchable: false,
+        data: {
+            "headings": [
+                "Implementation", 
+                "Short Name",
+                "Language",
+                "Licence",
+                "Supported Schema Versions",
+            ],
+            "data": implData.map(row => [ 
+                "<a href='" + row.url + "'>" + row.longName + "</a>", 
+                row.shortName, 
+                row.language,
+                row.licence,
+                row.supported.join(', '),
+            ])
+        }
+    });
+
+
+</script>

src/main/java/org/creekservice/kafka/test/perf/implementations/ConfluentImplementation.java

@@ -44,7 +44,10 @@ public class ConfluentImplementation implements Implementation {
             new MetaData(
                     "Confluent validating JSON serde",
                     "Confluent",
-                    Set.of(DRAFT_04, DRAFT_06, DRAFT_07));
+                    Language.Java,
+                    Licence.Apache_v2_0,
+                    Set.of(DRAFT_04, DRAFT_06, DRAFT_07),
+                    "https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/serdes-json.html");
 
     private static final String TOPIC_NAME = "t";
 

src/main/java/org/creekservice/kafka/test/perf/implementations/EveritImplementation.java

@@ -49,7 +49,13 @@
 public class EveritImplementation implements Implementation {
 
     private static final MetaData METADATA =
-            new MetaData("everit-org/json-schema", "Everit", Set.of(DRAFT_04, DRAFT_06, DRAFT_07));
+            new MetaData(
+                    "everit-org/json-schema",
+                    "Everit",
+                    Language.Java,
+                    Licence.Apache_v2_0,
+                    Set.of(DRAFT_04, DRAFT_06, DRAFT_07),
+                    "https://github.com/everit-org/json-schema");
 
     private ObjectMapper mapper = JsonMapper.builder().build();