Merge pull request #1410 from lesserwhirls/doc-build

Build docs using docker

Author: lesserwhirls

docs/build.gradle

@@ -1,9 +1,9 @@
 plugins {
   id 'base' // Adds 'assemble', 'check', 'build', and 'clean' tasks.
-  id 'edu.ucar.unidata.site.jekyll'
 }
 
 //////////////////////////////////////////////// Javadoc ////////////////////////////////////////////////
+apply from: "$rootDir/gradle/any/dependencies.gradle"
 apply from: "$rootDir/gradle/any/javadoc.gradle"
 apply from: "$rootDir/gradle/any/testing.gradle"
 
@@ -115,6 +115,65 @@ gradle.projectsEvaluated {  // Several statements below rely upon all subproject
 
 apply from: "$rootDir/gradle/any/properties.gradle"  // For Nexus credential properties.
 
+String docTheme = "unidata-jekyll-docs:0.0.4"
+
+boolean isGitHub = System.getenv('GITHUB_ACTIONS') as boolean
+String imageBaseUrl = "docker.unidata.ucar.edu"
+if (isGitHub) {
+  imageBaseUrl = "ghcr.io/unidata"
+}
+
+String dockerImage = "${imageBaseUrl}/${docTheme}"
+Provider<Directory> siteBuildDir = layout.buildDirectory.dir("site")
+
+tasks.register("buildJekyllSite", Exec) {
+  group = "documentation"
+  description = "Build the netCDF-Java documentation."
+  ConfigurableFileTree buildDocInputs = fileTree(".")
+  buildDocInputs.exclude("build/", ".gradle", ".jekyll-cache")
+  inputs.files(buildDocInputs)
+  outputs.dir(siteBuildDir)
+  commandLine("docker", "run", "--rm",
+      "-e", "SRC_DIR=/netcdf-java/docs/src/site",
+      "-v", "$rootDir:/netcdf-java",
+      "-v", "./${relativePath(siteBuildDir.get().toString())}:/site",
+      dockerImage, "build")
+}
+
+class NullOutputStream extends OutputStream {
+  @Override
+  void write(int b) throws IOException {}
+}
+
+tasks.register("serveJekyllSite", Exec) {
+  group = "documentation"
+  description = "Start a local server to live edit the netCDF-Java documentation."
+  commandLine("docker", "run", "--rm", "-d",
+      "--name", "netcdf-java-docs-server",
+        "-e", "SRC_DIR=/netcdf-java/docs/src/site",
+        "-v", "$rootDir:/netcdf-java",
+        "-p", "4005:4005",
+        dockerImage, "serve", "--livereload")
+  standardOutput = new NullOutputStream()
+  doLast {
+    String msg = "NetCDF-Java documentation available at http://localhost:4005"
+    String bannerBorder = new String(new char[msg.length() + 4]).replace("\0", "#");
+    println()
+    println(bannerBorder)
+    println("# $msg #")
+    println(bannerBorder)
+    println()
+  }
+}
+
+tasks.register("stopServe", Exec) {
+  group = "documentation"
+  description = "Stop the local server used while live editing the netCDF-Java documentation."
+  commandLine("docker", "stop", "netcdf-java-docs-server")
+  delete("$projectDir/src/site/Gemfile")
+  delete("$projectDir/src/site/Gemfile.lock")
+}
+
 import edu.ucar.build.publishing.tasks.PublishToRawRepoTask
 
 tasks.withType(PublishToRawRepoTask).all {  // Common PublishToRawRepoTask config.
@@ -134,16 +193,14 @@ tasks.withType(PublishToRawRepoTask).all {  // Common PublishToRawRepoTask confi
 
 tasks.register('publishAsVersionedUserGuide', PublishToRawRepoTask) {
   description = 'Publish user guide (versioned) to Nexus under /major.minor/.'
-
-  publishSrc = buildJekyllSite.destinationDirectory.get()
+  publishSrc = siteBuildDir.get().toString()
   destPath = "$project.docVersion/userguide/"
   dependsOn tasks.getByName('buildJekyllSite')
 }
 
 tasks.register('publishAsCurrentUserGuide', PublishToRawRepoTask) {
   description = 'Publish the user guide to Nexus under /current/.'
-
-  publishSrc = buildJekyllSite.destinationDirectory.get()
+  publishSrc = siteBuildDir.get().toString()
   destPath = 'current/userguide/'
   dependsOn tasks.getByName('buildJekyllSite')
 }

project-files/jenkins/pipelines/docs

@@ -0,0 +1,40 @@
+pipeline {
+    agent  { label 'main' }
+    stages {
+        stage('Build documentation') {
+            steps {
+                sh '''docker run --rm \
+                      -e SRC_DIR=/netcdf-java/docs/src/site \
+                      -e DOCS_UID=$(id -u) \
+                      -v .:/netcdf-java \
+                      -v ./docs/build/site:/site \
+                      docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4 build
+                '''
+            }
+        }
+        stage('Publish documentation') {
+            agent {
+                docker {
+                    image 'docker.unidata.ucar.edu/thredds-test-environment:latest'
+                    // Run the container on the node specified at the
+                    // top-level of the Pipeline, in the same workspace,
+                    // rather than on a new node entirely:
+                    reuseNode true
+                }
+            }
+            steps {
+                withCredentials([file(credentialsId: 'thredds_vault', variable: 'TV'), file(credentialsId: 'vault_pw', variable: 'AVP')]) {
+                    sh '''#!/bin/bash -l
+                    select-java temurin 11
+                    set +x
+                    ./gradlew \
+                      -Pnexus.username=`get_pw NEXUS_USER` \
+                      -Pnexus.password=`get_pw NEXUS_PW` \
+                      -x :docs:buildJekyllSite \
+                      :docs:publishAsVersionedUserGuide
+                    '''
+                }
+            }
+        }
+    }
+}