Improved a bit the docs website (#185)

* Improved a bit the docs Changed the docs website theme Signed-off-by: Francesco Guardiani <francescoguard@gmail.com> * Using constants Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>
2020-06-25 11:24:18 +02:00 · 2020-06-25 11:24:18 +02:00 · fd1e6b2728
parent 12cca34d21
commit fd1e6b2728
8 changed files with 380 additions and 12 deletions
--- a/.gitignore
+++ b/.gitignore
@ -34,3 +34,9 @@ release.properties

 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+
+# Jekyll stuff
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
--- a/README.md
+++ b/README.md
@ -7,6 +7,8 @@

 A Java API for the [CloudEvents specification](https://github.com/cloudevents/spec)

+Look at https://cloudevents.github.io/sdk-java/ for more documentation.
+
 __Checkout the [changelog](./CHANGELOG.md)__

 ## Status
--- a/core/README.md
+++ b/core/README.md
@ -41,8 +41,11 @@ add `cloudevents-json-jackson` as a dependency and then:

 ```java
 import io.cloudevents.core.format.EventFormatProvider;
+import io.cloudevents.jackson.JsonFormat;

-EventFormat format = EventFormatProvider.getInstance().resolveFormat("application/json");
+EventFormat format = EventFormatProvider
+  .getInstance()
+  .resolveFormat(JsonFormat.CONTENT_TYPE);

 // Serialize event
 byte[] serialized = format.serialize(event);
--- a/docs/Gemfile
+++ b/docs/Gemfile
@ -0,0 +1,30 @@
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+
+gem "jekyll", "~> 3.8.7"
+gem "github-pages", group: :jekyll_plugins
+
+gem "just-the-docs"
+
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.13"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
+  gem "tzinfo", "~> 1.2"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?
+
--- a/docs/Gemfile.lock
+++ b/docs/Gemfile.lock
@ -0,0 +1,262 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.0.3.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    coffee-script (2.4.1)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.11.1)
+    colorator (1.1.0)
+    commonmarker (0.17.13)
+      ruby-enum (~> 0.5)
+    concurrent-ruby (1.1.6)
+    dnsruby (1.61.3)
+      addressable (~> 2.5)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    ethon (0.12.0)
+      ffi (>= 1.3.0)
+    eventmachine (1.2.7)
+    execjs (2.7.0)
+    faraday (1.0.1)
+      multipart-post (>= 1.2, < 3)
+    ffi (1.13.1)
+    forwardable-extended (2.6.0)
+    gemoji (3.0.1)
+    github-pages (206)
+      github-pages-health-check (= 1.16.1)
+      jekyll (= 3.8.7)
+      jekyll-avatar (= 0.7.0)
+      jekyll-coffeescript (= 1.1.1)
+      jekyll-commonmark-ghpages (= 0.1.6)
+      jekyll-default-layout (= 0.1.4)
+      jekyll-feed (= 0.13.0)
+      jekyll-gist (= 1.5.0)
+      jekyll-github-metadata (= 2.13.0)
+      jekyll-mentions (= 1.5.1)
+      jekyll-optional-front-matter (= 0.3.2)
+      jekyll-paginate (= 1.1.0)
+      jekyll-readme-index (= 0.3.0)
+      jekyll-redirect-from (= 0.15.0)
+      jekyll-relative-links (= 0.6.1)
+      jekyll-remote-theme (= 0.4.1)
+      jekyll-sass-converter (= 1.5.2)
+      jekyll-seo-tag (= 2.6.1)
+      jekyll-sitemap (= 1.4.0)
+      jekyll-swiss (= 1.0.0)
+      jekyll-theme-architect (= 0.1.1)
+      jekyll-theme-cayman (= 0.1.1)
+      jekyll-theme-dinky (= 0.1.1)
+      jekyll-theme-hacker (= 0.1.1)
+      jekyll-theme-leap-day (= 0.1.1)
+      jekyll-theme-merlot (= 0.1.1)
+      jekyll-theme-midnight (= 0.1.1)
+      jekyll-theme-minimal (= 0.1.1)
+      jekyll-theme-modernist (= 0.1.1)
+      jekyll-theme-primer (= 0.5.4)
+      jekyll-theme-slate (= 0.1.1)
+      jekyll-theme-tactile (= 0.1.1)
+      jekyll-theme-time-machine (= 0.1.1)
+      jekyll-titles-from-headings (= 0.5.3)
+      jemoji (= 0.11.1)
+      kramdown (= 1.17.0)
+      liquid (= 4.0.3)
+      mercenary (~> 0.3)
+      minima (= 2.5.1)
+      nokogiri (>= 1.10.4, < 2.0)
+      rouge (= 3.19.0)
+      terminal-table (~> 1.4)
+    github-pages-health-check (1.16.1)
+      addressable (~> 2.3)
+      dnsruby (~> 1.60)
+      octokit (~> 4.0)
+      public_suffix (~> 3.0)
+      typhoeus (~> 1.3)
+    html-pipeline (2.13.0)
+      activesupport (>= 2)
+      nokogiri (>= 1.4)
+    http_parser.rb (0.6.0)
+    i18n (0.9.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.8.7)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 0.7)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 4)
+      safe_yaml (~> 1.0)
+    jekyll-avatar (0.7.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-coffeescript (1.1.1)
+      coffee-script (~> 2.2)
+      coffee-script-source (~> 1.11.1)
+    jekyll-commonmark (1.3.1)
+      commonmarker (~> 0.14)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-commonmark-ghpages (0.1.6)
+      commonmarker (~> 0.17.6)
+      jekyll-commonmark (~> 1.2)
+      rouge (>= 2.0, < 4.0)
+    jekyll-default-layout (0.1.4)
+      jekyll (~> 3.0)
+    jekyll-feed (0.13.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-gist (1.5.0)
+      octokit (~> 4.2)
+    jekyll-github-metadata (2.13.0)
+      jekyll (>= 3.4, < 5.0)
+      octokit (~> 4.0, != 4.4.0)
+    jekyll-mentions (1.5.1)
+      html-pipeline (~> 2.3)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-optional-front-matter (0.3.2)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-paginate (1.1.0)
+    jekyll-readme-index (0.3.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-redirect-from (0.15.0)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-relative-links (0.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-remote-theme (0.4.1)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      rubyzip (>= 1.3.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-swiss (1.0.0)
+    jekyll-theme-architect (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-cayman (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-dinky (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-hacker (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-leap-day (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-merlot (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-midnight (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-minimal (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-modernist (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-primer (0.5.4)
+      jekyll (> 3.5, < 5.0)
+      jekyll-github-metadata (~> 2.9)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-slate (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-tactile (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-theme-time-machine (0.1.1)
+      jekyll (~> 3.5)
+      jekyll-seo-tag (~> 2.0)
+    jekyll-titles-from-headings (0.5.3)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    jemoji (0.11.1)
+      gemoji (~> 3.0)
+      html-pipeline (~> 2.2)
+      jekyll (>= 3.0, < 5.0)
+    just-the-docs (0.2.9)
+      jekyll (>= 3.8.5, < 4.1.0)
+      jekyll-seo-tag (~> 2.0)
+      rake (>= 12.3.1, < 13.1.0)
+    kramdown (1.17.0)
+    liquid (4.0.3)
+    listen (3.2.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.3.6)
+    mini_portile2 (2.4.0)
+    minima (2.5.1)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-feed (~> 0.9)
+      jekyll-seo-tag (~> 2.1)
+    minitest (5.14.1)
+    multipart-post (2.1.1)
+    nokogiri (1.10.9)
+      mini_portile2 (~> 2.4.0)
+    octokit (4.18.0)
+      faraday (>= 0.9)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (3.1.1)
+    rake (13.0.1)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rouge (3.19.0)
+    ruby-enum (0.8.0)
+      i18n
+    rubyzip (2.3.0)
+    safe_yaml (1.0.5)
+    sass (3.7.4)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    sawyer (0.8.2)
+      addressable (>= 2.3.5)
+      faraday (> 0.8, < 2.0)
+    terminal-table (1.8.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    thread_safe (0.3.6)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    tzinfo-data (1.2020.1)
+      tzinfo (>= 1.0.0)
+    unicode-display_width (1.7.0)
+    wdm (0.1.1)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages
+  jekyll (~> 3.8.7)
+  jekyll-feed (~> 0.13)
+  just-the-docs
+  tzinfo (~> 1.2)
+  tzinfo-data
+  wdm (~> 0.1.1)
+
+BUNDLED WITH
+   2.1.4
--- a/docs/_config.yml
+++ b/docs/_config.yml
@ -1,3 +1,13 @@
-theme: jekyll-theme-slate
+# To configure the environment locally to test the website, check out
+# https://help.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll
+
+title: Java SDK for CloudEvents
+remote_theme: pmarsceill/just-the-docs
 plugins:
  - jemoji
+
+aux_links:
+  "GitHub Repository":
+    - "https://github.com/cloudevents/sdk-java"
+  "CloudEvents home":
+    - "https://cloudevents.io/"
--- a/docs/index.md
+++ b/docs/index.md
@ -1,3 +1,8 @@
+---
+title: Home
+nav_order: 1
+---
+
 # Java SDK for CloudEvents

 A Java API for the [CloudEvents specification](https://github.com/cloudevents/spec)
@ -6,6 +11,7 @@ A Java API for the [CloudEvents specification](https://github.com/cloudevents/sp
 1. [Modules](#modules)
 1. [Get Started](#get-started)
 1. [Use an event format](#use-an-event-format)
+1. [Use a protocol binding](#use-a-protocol-binding)

 ## Supported Specification Features

@ -18,6 +24,7 @@ Supported features of the specification:
 | AVRO Event Format             | :x: | :x: |
 | HTTP Protocol Binding         | :heavy_check_mark: | :heavy_check_mark: |
 | - [Vert.x](https://github.com/cloudevents/sdk-java/tree/master/http/vertx)        | :heavy_check_mark: | :heavy_check_mark: |
+| - [Jakarta Restful WS](https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws) | :heavy_check_mark: | :heavy_check_mark: |
 | JSON Event Format             | :heavy_check_mark: | :heavy_check_mark: |
 | - [Jackson](https://github.com/cloudevents/sdk-java/tree/master/formats/json-jackson) | :heavy_check_mark: | :heavy_check_mark: |
 | [Kafka Protocol Binding](https://github.com/cloudevents/sdk-java/tree/master/kafka)        | :heavy_check_mark: | :heavy_check_mark: |
@ -27,23 +34,71 @@ Supported features of the specification:

 ## Modules

-The CloudEvents SDK for Java is composed by several modules, each one providing a different feature from the different subspecs of [CloudEvents specification](#supported-specification-features):
+The CloudEvents SDK for Java is composed by several modules, each one providing a different feature from the different sub specs of [CloudEvents specification](#supported-specification-features):

-* [`cloudevents-core`](https://github.com/cloudevents/sdk-java/tree/master/api): Base module providing
-  * `CloudEvent` class, the in memory representation of a CloudEvent
-  * `CloudEventBuilder`, the builder to create `CloudEvent`s programmatically
-  * `EventFormat`, the abstraction to implement [Event Formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format)
-  * `Message`/`MessageVisitor`, the abstractions to implement [Protocol bindings](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding)
-* [`cloudevents-json-jackson`](https://github.com/cloudevents/sdk-java/tree/master/formats/json-jackson): Implementation of [JSON Event format] with [Jackson](https://github.com/FasterXML/jackson)
-* [`cloudevents-http-vertx`](https://github.com/cloudevents/sdk-java/tree/master/http/vertx): Implementation of [HTTP Protocol Binding] with [Vert.x Core](https://vertx.io/)
-* [`cloudevents-kafka`](https://github.com/cloudevents/sdk-java/tree/master/kafka): Implementation of [Kafka Protocol Binding]
+* [`cloudevents-api`] Module providing the `CloudEvent` and other base interfaces
+* [`cloudevents-core`] Module providing `CloudEvent` implementation, `CloudEventBuilder` to create `CloudEvent`s programmatically, `EventFormat` to implement [Event Formats](https://github.com/cloudevents/spec/blob/v1.0/spec.md#event-format), `Message`/`MessageVisitor` to implement [Protocol bindings](https://github.com/cloudevents/spec/blob/v1.0/spec.md#protocol-binding)
+* [`cloudevents-json-jackson`] Implementation of [JSON Event format] with [Jackson](https://github.com/FasterXML/jackson)
+* [`cloudevents-http-vertx`] Implementation of [HTTP Protocol Binding] with [Vert.x Core](https://vertx.io/)
+* [`cloudevents-http-restful-ws`] Implementation of [HTTP Protocol Binding] for [Jakarta Restful WS](https://jakarta.ee/specifications/restful-ws/)
+* [`cloudevents-kafka`] Implementation of [Kafka Protocol Binding]

 The latest SDK version is _2.0.0-SNAPSHOT_.

 ## Get Started

+You can start creating events using the `CloudEventBuilder`:
+
+```java
+import io.cloudevents.CloudEvent;
+import io.cloudevents.core.builder.CloudEventBuilder;
+import java.net.URI;
+
+final CloudEvent event = CloudEventBuilder.v1()
+    .withId("000")
+    .withType("example.demo")
+    .withSource(URI.create("http://example.com"))
+    .withData("application/json", "{}".getBytes())
+    .build();
+```
+
+Look at [`cloudevents-core`] README for more information.
+
 ## Use an event format

+Event formats implementations are auto-discovered through an SPI. You can use them accessing through `EventFormatProvider`.
+For example, given you have in your classpath the [`cloudevents-json-jackson`] module, you can serialize/deserialize an event to/from JSON using:
+
+```java
+import io.cloudevents.core.format.EventFormatProvider;
+import io.cloudevents.jackson.JsonFormat;
+
+EventFormat format = EventFormatProvider
+  .getInstance()
+  .resolveFormat(JsonFormat.CONTENT_TYPE);
+
+// Serialize event
+byte[] serialized = format.serialize(event);
+
+// Deserialize event
+CloudEvent event = format.deserialize(bytes);
+```
+
+## Use a protocol binding
+
+Each protocol binding has its own APIs, depending on the library/framework it's integrating with.
+Check out the documentation of the protocol binding modules:
+
+* [`cloudevents-http-vertx`]
+* [`cloudevents-http-restful-ws`]
+* [`cloudevents-kafka`]
+
 [JSON Event Format]: https://github.com/cloudevents/spec/blob/v1.0/json-format.md
 [HTTP Protocol Binding]: https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md
 [Kafka Protocol Binding]: https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md
+[`cloudevents-api`]: https://github.com/cloudevents/sdk-java/tree/master/api
+[`cloudevents-core`]: https://github.com/cloudevents/sdk-java/tree/master/core
+[`cloudevents-json-jackson`]: https://github.com/cloudevents/sdk-java/tree/master/formats/json-jackson
+[`cloudevents-http-vertx`]: https://github.com/cloudevents/sdk-java/tree/master/http/vertx
+[`cloudevents-http-restful-ws`]: https://github.com/cloudevents/sdk-java/tree/master/http/restful-ws
+[`cloudevents-kafka`]: https://github.com/cloudevents/sdk-java/tree/master/kafka
--- a/formats/json-jackson/README.md
+++ b/formats/json-jackson/README.md
@ -25,6 +25,6 @@ CloudEvent event = CloudEventBuilder.v1()

 byte[] serialized = EventFormatProvider
  .getInstance()
-  .resolveFormat("application/json")
+  .resolveFormat(JsonFormat.CONTENT_TYPE)
  .serialize(event);
 ```