New docs template and flow

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "docs/**"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: '${{ github.workspace }}/docs'
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: "docs/_site/"
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.3.2"
+gem "just-the-docs", "0.5.2"
+gem "jemoji"

docs/_config.yml

@@ -1,8 +1,10 @@
-# Theme
-theme: jekyll-theme-cayman
-# Site settings
-name: Symphony BDK for Java
-description: Symphony BDK (Bot Developer Kit) for Java developers
-# Plugins
+title: BDK 2.0 for Java
+description: Reference documentation for using the Symphony BDK to build bots
+theme: just-the-docs
 plugins:
-  - jemoji # https://docs.github.com/en/enterprise/2.13/user/articles/emoji-on-github-pages
+  - jemoji
+url: https://symphony-bdk-java.finos.org
+color_scheme: symphony
+aux_links:
+  "BDK 2.0 on GitHub":
+    - "//github.com/finos/symphony-bdk-java"

docs/_includes/anchor_headings.html

@@ -0,0 +1,174 @@
+{% capture headingsWorkspace %}
+  {% comment %}
+    Copyright (c) 2018 Vladimir "allejo" Jimenez
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following
+    conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.
+  {% endcomment %}
+  {% comment %}
+    Version 1.0.13
+      https://github.com/allejo/jekyll-anchor-headings
+
+    "Be the pull request you wish to see in the world." ~Ben Balter
+
+    Usage:
+      {% include anchor_headings.html html=content anchorBody="#" %}
+
+    Parameters:
+      * html          (string) - the HTML of compiled markdown generated by kramdown in Jekyll
+
+    Optional Parameters:
+      * beforeHeading (bool)   : false  - Set to true if the anchor should be placed _before_ the heading's content
+      * headerAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the heading tag; you may NOT use `id`;
+                                          the `%heading%` and `%html_id%` placeholders are available
+      * anchorAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the `<a>` tag; you may NOT use `href`, `class` or `title`;
+                                          the `%heading%` and `%html_id%` placeholders are available
+      * anchorBody    (string) :  ''    - The content that will be placed inside the anchor; the `%heading%` placeholder is available
+      * anchorClass   (string) :  ''    - The class(es) that will be used for each anchor. Separate multiple classes with a space
+      * anchorTitle   (string) :  ''    - The `title` attribute that will be used for anchors
+      * h_min         (int)    :  1     - The minimum header level to build an anchor for; any header lower than this value will be ignored
+      * h_max         (int)    :  6     - The maximum header level to build an anchor for; any header greater than this value will be ignored
+      * bodyPrefix    (string) :  ''    - Anything that should be inserted inside of the heading tag _before_ its anchor and content
+      * bodySuffix    (string) :  ''    - Anything that should be inserted inside of the heading tag _after_ its anchor and content
+      * generateId    (true)   :  false - Set to true if a header without id should generate an id to use.
+
+    Output:
+      The original HTML with the addition of anchors inside of all of the h1-h6 headings.
+  {% endcomment %}
+
+  {% assign minHeader = include.h_min | default: 1 %}
+  {% assign maxHeader = include.h_max | default: 6 %}
+  {% assign beforeHeading = include.beforeHeading %}
+  {% assign headerAttrs = include.headerAttrs %}
+  {% assign nodes = include.html | split: '<h' %}
+
+  {% capture edited_headings %}{% endcapture %}
+
+  {% for _node in nodes %}
+    {% capture node %}{{ _node | strip }}{% endcapture %}
+
+    {% if node == "" %}
+      {% continue %}
+    {% endif %}
+
+    {% assign nextChar = node | replace: '"', '' | strip | slice: 0, 1 %}
+    {% assign headerLevel = nextChar | times: 1 %}
+
+    <!-- If the level is cast to 0, it means it's not a h1-h6 tag, so let's see if we need to fix it -->
+    {% if headerLevel == 0 %}
+      <!-- Split up the node based on closing angle brackets and get the first one. -->
+      {% assign firstChunk = node | split: '>' | first %}
+
+      <!-- If the first chunk does NOT contain a '<', that means we've broken another HTML tag that starts with 'h' -->
+      {% unless firstChunk contains '<' %}
+        {% capture node %}<h{{ node }}{% endcapture %}
+      {% endunless %}
+
+      {% capture edited_headings %}{{ edited_headings }}{{ node }}{% endcapture %}
+      {% continue %}
+    {% endif %}
+
+    {% capture _closingTag %}</h{{ headerLevel }}>{% endcapture %}
+    {% assign _workspace = node | split: _closingTag %}
+    {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}
+    {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}
+    {% assign escaped_header = header | strip_html | strip %}
+
+    {% assign _classWorkspace = _workspace[0] | split: 'class="' %}
+    {% assign _classWorkspace = _classWorkspace[1] | split: '"' %}
+    {% assign _html_class = _classWorkspace[0] %}
+
+    {% if _html_class contains "no_anchor" %}
+      {% assign skip_anchor = true %}
+    {% else %}
+      {% assign skip_anchor = false %}
+    {% endif %}
+
+    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
+    {% if _idWorkspace[1] %}
+      {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
+      {% assign html_id = _idWorkspace[0] %}
+      {% assign h_attrs = headerAttrs %}
+    {% elsif include.generateId %}
+      <!-- If the header did not have an id we create one. -->
+      {% assign html_id = escaped_header | slugify %}
+      {% if html_id == "" %}
+        {% assign html_id = false %}
+      {% endif %}
+      <!-- Append the generated id to other potential header attributes. -->
+      {% capture h_attrs %}{{ headerAttrs }} id="%html_id%"{% endcapture %}
+    {% endif %}
+
+    <!-- Build the anchor to inject for our heading -->
+    {% capture anchor %}{% endcapture %}
+
+    {% if skip_anchor == false and html_id and headerLevel >= minHeader and headerLevel <= maxHeader %}
+      {% if h_attrs %}
+        {% capture _hAttrToStrip %}{{ _hAttrToStrip | split: '>' | first }} {{ h_attrs | strip | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}>{% endcapture %}
+      {% endif %}
+
+      {% capture anchor %}href="#{{ html_id }}"{% endcapture %}
+
+      {% if include.anchorClass %}
+        {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %}
+      {% endif %}
+
+      {% if include.anchorTitle %}
+        {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', escaped_header }}"{% endcapture %}
+      {% endif %}
+
+      {% if include.anchorAttrs %}
+        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}{% endcapture %}
+      {% endif %}
+
+      {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', escaped_header | default: '' }}</a>{% endcapture %}
+
+      <!-- In order to prevent adding extra space after a heading, we'll let the 'anchor' value contain it -->
+      {% if beforeHeading %}
+        {% capture anchor %}{{ anchor }} {% endcapture %}
+      {% else %}
+        {% capture anchor %} {{ anchor }}{% endcapture %}
+      {% endif %}
+    {% endif %}
+
+    {% capture new_heading %}
+<h{{ _hAttrToStrip }}
+  {{ include.bodyPrefix }}
+  {% if beforeHeading %}
+    {{ anchor }}{{ header }}
+  {% else %}
+    {{ header }}{{ anchor }}
+  {% endif %}
+  {{ include.bodySuffix }}
+</h{{ headerLevel }}>
+    {% endcapture %}
+
+    <!--
+    If we have content after the `</hX>` tag, then we'll want to append that here so we don't lost any content.
+    -->
+    {% assign chunkCount = _workspace | size %}
+    {% if chunkCount > 1 %}
+      {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %}
+    {% endif %}
+
+    {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %}
+  {% endfor %}
+{% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }}

docs/_includes/nav_footer_custom.html

@@ -0,0 +1 @@
+ 

docs/_layouts/base.html

@@ -0,0 +1 @@
+{% include anchor_headings.html html=content anchorBody="#" %}

docs/_sass/color_schemes/symphony.scss

@@ -0,0 +1 @@
+$link-color: #116fb9;

docs/activity-api.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Activity API
+nav_order: 17
+---
+
 # Activity API
 
 The Activity API is an abstraction built on top of the Datafeed's [_Real Time Events_](https://docs.developers.symphony.com/building-bots-on-symphony/datafeed/real-time-events). An Activity is basically a user interaction triggered from the chat.
@@ -143,41 +149,6 @@ public class Example {
 3. the command callback provides the `CommandContext` that allows to retrieve some information about the source of the
 event, or the event initiator (i.e. user that triggered the command)
 
-### Async Slash Command
-A slash command is synchronous by default. In case the process takes times, the others incoming commands will be queued
-and get executed when the blocking process is released. If it is a concern, Slash command can be asynchronous by passing
-`asynchronous` parameter to the annotation. 
-
-```java
-@Slf4j
-public class AsyncCommandMain {
-  public static void main(String[] args) throws Exception {
-
-    // setup SymphonyBdk facade object
-    final SymphonyBdk bdk = new SymphonyBdk(loadFromClasspath("/config.yaml"));
-
-    // displays the Gif form on /gif command with no params
-    bdk.activities().register(slash("/async",  // (1)
-            false,                              // (2)
-            true,                              // (3)
-            context ->                         // (4)
-                    bdk.messages().send(context.getStreamId(), 
-                            "This is an asynchronous command that should not block next commands"), 
-            "Asynchronous command example"    // (5)
-    ));
-
-    // finally, start the datafeed loop
-    bdk.datafeed().start();
-  }
-}
-```
-1. `/async` is the command pattern
-2. `false` means that the bot should not be mentioned in the command
-3. `true` means that the command will be executed asynchronously
-4. the command callback provides the `CommandContext` that allows to retrieve some information about the source of the
-   event, or the event initiator (i.e. user that triggered the command)
-5. the command description
-
 ### Help Command
 
 _Help_ command is a BDK built-in command which will list out all the commands registered in the `ActivityRegistry` of the BDK by:
@@ -275,4 +246,4 @@ submitted from the action button "**submit**"
 2. The activity context allows to directly retrieve form values. Here the "**name**" `<text-field>` value
 
 ----
-[Home :house:](./index.md)
+[Home :house:](./index.html)

docs/application.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Application API
+nav_order: 12
+---
+
 # Application API
 
 The Application Service is a component at the service layer of the BDK which aims to cover the Applications part of the [REST API documentation](https://developers.symphony.com/restapi/reference).

docs/authentication.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Authentication
+nav_order: 5
+---
+
 # Authentication
 The Symphony BDK authentication API allows developers to authenticate their bots and apps using either RSA or
 certificate authentication modes.
@@ -225,4 +231,4 @@ public class Example {
 ```
 
 ----
-[Home :house:](./index.md)
+[Home :house:](./index.html)