Use the official Jekyll container to build the site

Using a container makes it much easier to ensure consistency between
different developer environments, and even avoids devs needing to setup
an environment and deal with dependency issues.

- Update the README to describe how to test locally using the Jekyll
  container

- Update GitHub Actions to use the official Jekyll container

- Update GitHub Actions to run on pull requests, but with the publish
  step skipped, so that PRs can test that everything builds correctly
  before being merged

- Commit the Gemfile.lock file to freeze dependency versions

- Remove asciidoc descriptions for blockdiag, seqdiag, actdiag, and
  netdiag. The dependencies for these diagrams aren't easily added to
  the Jekyll container, we don't use any of them, and there is no
  obvious benefit to them over PlantUML or GraphViz

DAFFODIL-2595

.apk

@@ -0,0 +1 @@
+graphviz

.github/workflows/main.yml

@@ -13,45 +13,32 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: Publish Daffodil Site
+name: CI
 
-on: [push]
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize, reopened]
 
 jobs:
-  test:
-    name: Publish Site
-    runs-on: ubuntu-latest
+  build-publish:
+    name: Build & Publish
+    runs-on: ubuntu-20.04
     strategy:
       fail-fast: false
-    steps:
 
+    steps:
       - name: Checkout Repository
-        uses: actions/checkout@v1.0.0
-
-      - name: Install Ruby
-        uses: actions/setup-ruby@v1
+        uses: actions/checkout@v2.4.0
         with:
-          ruby-version: '2.6'
+          fetch-depth: 0
 
-      - name: Install Python
-        uses: actions/setup-python@v1
+      - name: Build
+        uses: docker://jekyll/jekyll:4.2.0
+        env:
+          JEKYLL_ROOTLESS: 1
         with:
-          python-version: '3.5'
-
-      - name: Install Dependencies
-        run: |
-          sudo apt-get install graphviz
-          bundle install
-          python -m pip install --upgrade pip
-          pip install blockdiag
-          pip install seqdiag
-          pip install actdiag
-          pip install nwdiag
-
-      - name: Build 
-        run: |
-          jekyll clean --source site
-          jekyll build --source site
+          args: jekyll build --source site
 
       - name: Publish
         if: ${{ github.repository == 'apache/daffodil-site' && github.ref == 'refs/heads/main' }}

.gitignore

@@ -13,8 +13,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-Gemfile.lock
 target
 .jekyll-cache/
-.idea/
-daffodil-site.iml

Gemfile

@@ -15,7 +15,5 @@
 
 source 'https://rubygems.org'
 
-gem 'jekyll', '= 4.2.0'
 gem 'jekyll-asciidoc', '= 3.0.0'
-gem 'asciidoctor-diagram', '= 2.0.1'
-gem 'webrick', '>=1.7.0'
+gem 'asciidoctor-diagram', '= 2.2.1'

Gemfile.lock

@@ -0,0 +1,79 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    asciidoctor (2.0.16)
+    asciidoctor-diagram (2.2.1)
+      asciidoctor (>= 1.5.7, < 3.x)
+      asciidoctor-diagram-ditaamini (~> 1.0)
+      asciidoctor-diagram-plantuml (~> 1.2021)
+      rexml
+    asciidoctor-diagram-ditaamini (1.0.1)
+    asciidoctor-diagram-plantuml (1.2021.8)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.9)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.15.4)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.8.0)
+    i18n (1.8.11)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.1)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-asciidoc (3.0.0)
+      asciidoctor (>= 1.5.0)
+      jekyll (>= 3.0.0)
+    jekyll-sass-converter (2.1.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.3.1)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.7.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    rb-fsevent (0.11.0)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.26.1)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.8.0)
+
+PLATFORMS
+  x86_64-linux-musl
+
+DEPENDENCIES
+  asciidoctor-diagram (= 2.2.1)
+  jekyll-asciidoc (= 3.0.0)
+
+BUNDLED WITH
+   2.2.24

README.md

@@ -23,58 +23,41 @@ The Apache Daffodil website is based off of the [Apache Website Template](https:
 
 The website is generated using [Jekyll](https://jekyllrb.com/) and some plug-ins for it.
 
-# How to deploy this web site
+## Testing Locally
 
-## Install Ruby Bundler
+To improve reproducibility and to minimize the effects and variability of a
+users environment, it is recommended that changes to the site repo be tested
+locally with a container. To do so, run one of the following commands.
 
-Some Linux distributions provide the Ruby Bundler via their package managers, for example, for Fedora:
+With docker:
 
-    $ dnf install rubygem-bundler
+    docker run -it --rm \
+      --publish 127.0.0.1:4000:4000 \
+      --volume="$PWD:/srv/jekyll" \
+      docker.io/jekyll/jekyll:4.2.0 \
+      jekyll serve --watch --source site
 
-## Install or Update Site Dependencies
+With rootless podman:
 
-    $ gem install
+    podman run -it --rm \
+      --publish 127.0.0.1:4000:4000 \
+      --volume="$PWD:/srv/jekyll" \
+      --env JEKYLL_ROOTLESS=1 \
+      docker.io/jekyll/jekyll:4.2.0 \
+      jekyll serve --watch --source site
 
-or
-
-    $ gem update
-
-## Install Jekyll Plug-ins for AsciiDoc and Diagram Rendering
-
-Some content is developed using the AsciiDoc Markdown variant, which supports
-embedded diagrams created from diagram-specifying text formats. 
-
-(You probably want to install these as super-user using sudo.)
-
-    $ apt install python-pip
-    $ pip install blockdiag
-    $ pip install seqdiag
-    $ pip install actdiag
-    $ pip install nwdiag
-
-NOTE: `nwdiag` actually supports more than one diagram type. It supports nwdiag, packetdiag, rackdiag, etc.
-
-## Running Locally
-
-Before opening a pull request, you can preview your contributions by
-running from within the directory:
-
-    $ jekyll serve --watch --source site
-
-If that fails to work due to missing jekyll plugin versions, try:
-
-    $ bundle exec jekyll serve --watch --source site
-
-Open [http://localhost:4000](http://localhost:4000) to view the site served by Jekyll.
+Then open [http://localhost:4000](http://localhost:4000) to view the site
+served by the Jekyll container. Changes to files in the site directory are
+automatically rebuilt and served.
 
 Once satisfied, create a branch and open a pull request using the Daffodil
 project [Code Conttributor Workflow](https://cwiki.apache.org/confluence/display/DAFFODIL/Code+Contributor+Workflow)
 but using the website repo instead of the code repo.
 
-## Pushing to the Live Site
+## Publishing to the Live Site
 
 Daffodil uses [gitpubsub](https://www.apache.org/dev/gitpubsub.html) for
-publishing to the website. The static content served via apache must be served
-in the ``content`` directory on the ``asf-site`` orphan branch. When the changes
+publishing to the website. The static content served via Apache must be served
+in the ``content`` directory on the ``asf-site`` orphan branch. When changes
 are merged into the main branch on GitHub, a GitHub action will automatically
-be triggered and it will perform the necessary steps to publish the site.
+run and perform the necessary steps to publish the site.

site/dev/aboutAsciiDoc.adoc

@@ -190,85 +190,6 @@ digraph structs {
 }
 ....
 
-== Example Block Diagram
-The http://blockdiag.com/en/blockdiag/[blockdiag] diagram type is for basic box/arrow diagrams.
-
-CAUTION: It is not clear how this compares for ease-of-use with PlantUML or GraphViz.
-
-[blockdiag]
-....
-blockdiag {
-  Kroki -> generates -> "Block diagrams";
-  Kroki -> is -> "very easy!";
-
-  Kroki [color = "greenyellow"];
-  "Block diagrams" [color = "pink"];
-  "very easy!" [color = "orange"];
-}
-....
-
-=== Sequence Diagram
-The http://blockdiag.com/en/seqdiag/[seqdiag] diagram type creates sequence diagrams. 
-
-CAUTION: It is not clear how this compares for ease-of-use with PlantUML sequence diagrams.
-
-[seqdiag]
-....
-seqdiag {
-  browser  -> webserver [label = "GET /seqdiag/svg/base64"];
-  webserver  -> processor [label = "Convert text to image"];
-  webserver <-- processor;
-  browser <-- webserver;
-}
-....
-=== Activity Diagram
-The http://blockdiag.com/en/actdiag/[actdiag] diagram type creates sequence diagrams. 
-
-CAUTION: It is not clear how this compares for ease-of-use with PlantUML activity diagrams.
-[actdiag]
-....
-actdiag {
-  write -> convert -> image
-
-  lane user {
-     label = "User"
-     write [label = "Writing reST"];
-     image [label = "Get diagram IMAGE"];
-  }
-  lane actdiag {
-     convert [label = "Convert reST to Image"];
-  }
-}
-....
-=== Network Diagram
-I don't know how much call we will have for these, but the
-http://blockdiag.com/en/nwdiag/[nwdiag] diagram type creates network diagrams which are interesting anyway.
-
-CAUTION: It is not clear how this compares for ease-of-use with PlantUML diagrams.
-
-[nwdiag]
-....
-nwdiag {
-  network dmz {
-      address = "210.x.x.x/24"
-
-      // set multiple addresses (using comma)
-      web01 [address = "210.x.x.1, 210.x.x.20"];
-      web02 [address = "210.x.x.2"];
-  }
-  network internal {
-      address = "172.x.x.x/24";
-
-      web01 [address = "172.x.x.1"];
-      web02 [address = "172.x.x.2"];
-      db01;
-      db02;
-  }
-}
-....
-
-== More GraphViz Examples
-
 === GraphViz Ad-Hoc Diagram
 Random boxes and ovals and other shapes.