Skip to content
Permalink
Browse files
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
  • Loading branch information
stevedlawrence committed Dec 19, 2021
1 parent 9a8b0ef commit 456ee18b44ea3ef76a97425c59310e0f42889503
Showing 7 changed files with 121 additions and 155 deletions.
1 .apk
@@ -0,0 +1 @@
graphviz
@@ -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' }}
@@ -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
@@ -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'
@@ -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
@@ -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.
@@ -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.

0 comments on commit 456ee18

Please sign in to comment.