Merge pull request #23 from lesserwhirls/docker

Release and docker image for building

README.md

@@ -132,3 +132,36 @@ As this theme progresses, we will add more details about Unidata specific extens
 The `utilities/` directory contains some potentially useful scripts from the upstream repository for generating tags and pdf docs.
 They were sort of cluttering up the main directory of the repo, so I moved them.
 
+## Build docs using docker
+
+To serve the unidata-jekyll-theme using the unidata-jekyll-docs image, go to the top of this repository and run:
+
+```shell
+docker run -it --rm -e SRC_DIR="/unidata-jekyll-theme" -v .:/unidata-jekyll-theme -p 4000:4000 docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4 serve --livereload
+```
+
+The SRC_DIR environment variable must be set.
+It should be the path to the directory _inside the container_ that holds the jekyll `_config.yml` file.
+This should be a directory at or under the bind mount point.
+
+Similarly, to build using the unidata-jekyll-docs image:
+
+```shell
+docker run -it --rm -e DOCS_UID=$(id -u) -e SRC_DIR="/unidata-jekyll-theme" -v .:/unidata-jekyll-theme -v ./_site:/site docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4 build
+```
+
+Note the additional bind mount `-v ./_site:/site` and the inclusion of `-e DOCS_UID=$(id -u)`.
+The additional bind mount is used define where the rendered documentation should be saved.
+The `DOCS_UID` environment variable is used to ensure the permissions of the rendered site files are correct.
+
+### A note on SRC_DIR
+
+Coordinating `SRC_DIR` and the bind mount containing the necessary files for a successful build can be tricky when the `includecodeblock` functionality of the unidata-jekyll-plugins is used.
+
+For example, to serve the documentation of the netCDF-Java project for live editing, you would run the following from the root directory of the project:
+
+```sh
+docker run -it --rm -e SRC_DIR="/netcdf-java/docs/src/site" -v .:/netcdf-java -p 4005:4005 unidata-jekyll-docs:latest serve --livereload
+```
+
+Because the netCDF-Java documentation uses code snippets from outside the main documentation directory (`/netcdf-java/docs/src/site`), we have to bind mount the entire project.

docker/Dockerfile

@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1
+FROM docker.io/ruby:3.4.1
+EXPOSE 4000/tcp
+
+ENV DOCS_UID=1000
+
+WORKDIR /doc_bootstrap
+COPY Gemfile .
+RUN bundle install
+
+COPY --chmod=700 entrypoint.sh /
+
+WORKDIR /
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["-h"]

docker/Gemfile

@@ -0,0 +1,5 @@
+source 'https://artifacts.unidata.ucar.edu/repository/gems/'
+
+gem 'unidata-jekyll-theme', '0.0.4'
+gem 'unidata-jekyll-plugins', '0.0.3'
+

docker/README.md

@@ -0,0 +1,22 @@
+Release
+
+* make sure you are logged into the artifacts server using docker
+  ```
+  docker login docker.unidata.ucar.edu -u <nexus-username>
+  ```
+* make sure you are logged into the GitHub Container Registry (using a classic personal access token [following these instructions](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry))
+  ```
+  docker login ghcr.io -u <github-username>
+  ```
+* bump theme/plugin versions in the Gemfile contained in this directory
+* run `build.sh` to create a local multi-platform image
+* tag the latest image with the release version for docker.unidata.ucar.edu and ghcr:
+  ```
+  docker image tag unidata-jekyll-docs:latest docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4
+  docker image tag unidata-jekyll-docs:latest ghcr.io/unidata/unidata-jekyll-docs:0.0.4
+  ```
+* push the new images
+  ```
+  docker image push docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4
+  docker image push ghcr.io/unidata/unidata-jekyll-docs:0.0.4
+  ```

docker/build.sh

@@ -0,0 +1 @@
+docker build --platform linux/amd64,linux/arm64 -t unidata-jekyll-docs:latest .

docker/entrypoint.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+# Intended to be user configurable
+# Required
+if [ -z "${SRC_DIR}" ]; then
+    echo "You must define the SRC_DIR environment variable. Exiting."
+    exit
+fi
+
+# need to work in src dir in order for includecodeblock
+# to work
+cd "${SRC_DIR}"
+
+# Not intended to be user configurable
+BOOTSTRAP_DIR="/doc_bootstrap"
+OUTPUT_DIR="/site"
+GEMFILE_NAME="Gemfile"
+GEMFILE_LOCK_NAME="${GEMFILE_NAME}.lock"
+DEFAULT_GEMFILE="${BOOTSTRAP_DIR}/${GEMFILE_NAME}"
+DEFAULT_GEMFILE_LOCK="${BOOTSTRAP_DIR}/${GEMFILE_LOCK_NAME}"
+
+SRC_GEMFILE="${SRC_DIR}/${GEMFILE_NAME}"
+SRC_GEMFILE_LOCK="${SRC_DIR}/${GEMFILE_LOCK_NAME}"
+REMOVE_GEMFILE=false
+CHOWN=false
+
+# If source Gemfile does not exist, copy over the default (and lock file)
+# for the unidata-jekyll-theme
+if [ ! -f "${SRC_GEMFILE}" ]; then
+    cp ${DEFAULT_GEMFILE} ${SRC_GEMFILE}
+    cp ${DEFAULT_GEMFILE_LOCK} ${SRC_GEMFILE_LOCK}
+    REMOVE_GEMFILE=true
+else
+    bundle install
+fi
+
+# attach jekyll to 0.0.0.0 so that jekyll serve can
+# be outside of the container
+ARG=${1}
+if [ "${ARG}" = "serve" ] ; then
+    ARG="serve --host 0.0.0.0"
+else
+    CHOWN=true
+fi
+
+if [[ ! -e "${OUTPUT_DIR}" ]]; then
+    mkdir "${OUTPUT_DIR}"
+fi
+
+bundle exec jekyll ${ARG} --destination "${OUTPUT_DIR}"
+
+if [ "${REMOVE_GEMFILE}" = true ] ; then
+    rm "${SRC_GEMFILE}"
+    rm "${SRC_GEMFILE_LOCK}"
+fi
+
+if [ "${CHOWN}" = true ] ; then
+    chown -R ${DOCS_UID} "${OUTPUT_DIR}"
+fi

unidata-jekyll-plugins.gemspec

@@ -2,7 +2,8 @@
 
 Gem::Specification.new do |spec|
     spec.name          = "unidata-jekyll-plugins"
-    spec.version       = "0.0.2"
+    spec.version       = "0.0.3"
+    spec.required_ruby_version = ">= 3.4.1"
     spec.authors       = ["Unidata"]
     spec.email         = ["[email protected]"]
 
@@ -14,5 +15,5 @@ Gem::Specification.new do |spec|
     spec.files       = all_files.grep(%r!^(_plugins)/!)
     spec.require_paths = ["_plugins"]
 
-    spec.add_runtime_dependency "jekyll"
+    spec.add_runtime_dependency "jekyll", "~> 4.4.1"
   end

unidata-jekyll-theme.gemspec

@@ -2,7 +2,8 @@
 
 Gem::Specification.new do |spec|
     spec.name          = "unidata-jekyll-theme"
-    spec.version       = "0.0.3"
+    spec.version       = "0.0.4"
+    spec.required_ruby_version = ">= 3.4.1"
     spec.authors       = ["Unidata"]
     spec.email         = ["[email protected]"]
 
@@ -12,6 +13,7 @@ Gem::Specification.new do |spec|
 
     spec.files         = `git ls-files -z`.split("\x0").select { |f| f.match(%r!^(_includes|_layouts|assets|licenses|README|_config\.yml|version-info.json)!) }
 
-    spec.add_runtime_dependency "jekyll"
-    spec.add_runtime_dependency "unidata-jekyll-plugins", '~> 0.0', '>= 0.0.2'
+    spec.add_runtime_dependency "jekyll", "~> 4.4.1"
+    spec.add_runtime_dependency "logger", "~> 1.6.5"
+    spec.add_runtime_dependency "unidata-jekyll-plugins", "~> 0.0.3"
   end