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
diff --git a/.apk b/.apk
new file mode 100644
index 0000000..4d95609
--- /dev/null
+++ b/.apk
@@ -0,0 +1 @@
+graphviz
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index b5bde2a..726f4cf 100644
--- a/.github/workflows/main.yml
+++ b/.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:
-
- 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' }}
diff --git a/.gitignore b/.gitignore
index bb26733..5a581bd 100644
--- a/.gitignore
+++ b/.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
diff --git a/Gemfile b/Gemfile
index d7a7aca..c7677f2 100644
--- a/Gemfile
+++ b/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'
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..e405832
--- /dev/null
+++ b/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
diff --git a/README.md b/README.md
index aa2bf06..06ba62f 100644
--- a/README.md
+++ b/README.md
@@ -23,58 +23,41 @@
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.
diff --git a/site/dev/aboutAsciiDoc.adoc b/site/dev/aboutAsciiDoc.adoc
index 7ec9593..07b421f 100644
--- a/site/dev/aboutAsciiDoc.adoc
+++ b/site/dev/aboutAsciiDoc.adoc
@@ -190,85 +190,6 @@
}
....
-== 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.
