Skip to content

Commit

Permalink
Merge pull request #567 from lesserwhirls/docker-docs
Browse files Browse the repository at this point in the history
Build docs using docker
  • Loading branch information
lesserwhirls authored Feb 6, 2025
2 parents 31c611f + 986849a commit 5ce926d
Show file tree
Hide file tree
Showing 8 changed files with 159 additions and 23 deletions.
3 changes: 0 additions & 3 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,6 @@ buildscript {
filter {
includeModule 'com.burgstaller', 'okhttp-digest'
includeModule 'org.ysb33r.gradle', 'grolifant'
includeModule 'edu.ucar.unidata.site', 'jekyll-plugin'
includeModule 'edu.ucar.unidata.site', 'jekyll-gems'
includeModule 'edu.ucar.unidata', 'unidata-nexus-gradle'
}
}
Expand All @@ -40,7 +38,6 @@ buildscript {
classpath buildPlugins.spotless
classpath buildPlugins.protobuf
classpath buildPlugins.nexus
classpath buildPlugins.jekyll
classpath buildPlugins.depcheck
}
}
Expand Down
3 changes: 2 additions & 1 deletion docs/.gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# copies of shared files used by documentation build
**/_data/topnav.yml
**/sitemap*.xml
**/sitemap*.xml
*/.jekyll-cache
7 changes: 7 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

All gradle commands shown below must be run from the top level of the TDS repository.

## Requirements

In addition to Java, Docker is now required for building the TDS docsets.

## Jekyll-based documentation

All docsets are published in the Nexus raw repository `docs-tds`.
Expand Down Expand Up @@ -32,6 +36,9 @@ For more information, see [shared/README.md](shared/README.md).

* Serve
* same as `build*` tasks above, but using `serve*` (e.g. `./gradlew :docs:serveUserGuide`)
* useful for live editing, as changes to .md files will be picked up and content regenerated on the fly
* note that only one docset can be served at a time
* when finished serving a doc set, run `./gradlew :docs:stopServe` to shutdown the docker container hosting the server

* Build all Jekyll-based sites (shortcut for building all jekyll-based documentation sets)
* `./gradlew :docs:buildAllJekyllSites`
Expand Down
2 changes: 1 addition & 1 deletion docs/adminguide/src/site/pages/thredds/WmsConfig.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Several properties related to the generation of images from the WMS service can
By default, this file is located in the `${tds.content.root.path}/thredds` directory.
An example `wmsConfig.xml` file is shipped with the TDS, which looks like:

{% capture rmd %}{% includefile ../tds/src/main/webapp/WEB-INF/altContent/startup/wmsConfig.xml %}{% endcapture %}
{% capture rmd %}{% includefile ../../../../tds/src/main/webapp/WEB-INF/altContent/startup/wmsConfig.xml %}{% endcapture %}

~~~xml
{{ rmd }}
Expand Down
70 changes: 54 additions & 16 deletions docs/build.gradle
Original file line number Diff line number Diff line change
@@ -1,18 +1,12 @@
plugins {
id 'base'
id 'edu.ucar.unidata.site.jekyll'
}

// disable tasks added by the jekyll plugin...we need custom tasks, one for each docset
buildJekyllSite.enabled(false)
serveJekyllSite.enabled(false)

apply from: "${rootDir}/gradle/any/properties.gradle"
apply from: "${projectDir}/helpers.gradle"

import edu.ucar.build.publishing.tasks.PublishToRawRepoTask
import edu.ucar.build.publishing.tasks.DeleteFromNexusTask
import edu.ucar.unidata.site.jekyll.tasks.ServeTask

////////////////////////
// Jekyll Sites Build //
Expand Down Expand Up @@ -59,31 +53,75 @@ tasks.register(buildAllJekyllSitesTaskName) {
description = 'Build all jekyll sites.'
}

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}"

class NullOutputStream extends OutputStream {
@Override
void write(int b) throws IOException {}
}

// setup build and publish tasks associated with each individual documentation set
docsets.each { docset ->
def partialTaskName = makeUpperCamelCase(docset)
def buildTask = tasks.register("build${partialTaskName}", edu.ucar.unidata.site.jekyll.tasks.BuildTask) {
Provider<Directory> siteBuildDir = layout.buildDirectory.dir("site/${docset}")
def buildTask = tasks.register("build${partialTaskName}", Exec) {
group 'documentation-set'
script = 'jekyll'
description "Build ${docset} jekyll site."
sourceDirectory.set(layout.projectDirectory.dir("${docset}/src/site"))
destinationDirectory.set(layout.buildDirectory.dir("site/${docset}/"))
dependsOn tasks.named('unpackGemJar'), copySharedJekyllFilesTask
ConfigurableFileTree buildDocInputs = fileTree("./${docset}/src/site")
buildDocInputs.exclude(".jekyll-cache")
inputs.files(buildDocInputs)
outputs.dir(siteBuildDir)
commandLine("docker", "run", "--rm",
"-e", "SRC_DIR=/tds/docs/${docset}/src/site",
"-v", "${rootDir}:/tds",
"-v", "./${relativePath(siteBuildDir.get().toString())}:/site",
dockerImage, "build")
dependsOn copySharedJekyllFilesTask
}

tasks.register("serve${partialTaskName}", ServeTask) {
tasks.register("serve${partialTaskName}", Exec) {
group 'documentation-set'
script = 'jekyll'
description "Serve $docset jekyll site."
sourceDirectory.set(layout.projectDirectory.dir("${docset}/src/site"))
destinationDirectory.set(layout.buildDirectory.dir("site/${docset}/"))
dependsOn tasks.named('unpackGemJar')
commandLine("docker", "run", "--rm", "-d",
"--name", "tds-docs-server",
"-e", "SRC_DIR=/tds/docs/${docset}/src/site",
"-v", "${rootDir}:/tds",
"-p", "4005:4005",
dockerImage, "serve", "--livereload")
standardOutput = new NullOutputStream()
dependsOn copySharedJekyllFilesTask
doLast {
String msg = "TDS ${docset} available at http://localhost:4005"
String bannerBorder = new String(new char[msg.length() + 4]).replace("\0", "#");
println()
println(bannerBorder)
println("# $msg #")
println(bannerBorder)
println()
}
}

// register tasks with the aggregator build task
tasks.named(buildAllJekyllSitesTaskName).configure({dependsOn buildTask})
}

tasks.register("stopServe", Exec) {
group = "documentation-set"
description = "Stop the local server used while live editing a tds documentation set."
commandLine("docker", "stop", "tds-docs-server")
docsets.each { docset ->
delete("${projectDir}/${docset}/src/site/Gemfile")
delete("${projectDir}/${docset}/src/site/Gemfile.lock")
}
}

/////////////////////////////////////////////
// Nexus Repository Publication Management //
/////////////////////////////////////////////
Expand Down
2 changes: 1 addition & 1 deletion docs/userguide/src/site/pages/thredds/WmsConfig.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Several properties related to the generation of images from the WMS service can
By default, this file is located in the `${tds.content.root.path}/thredds` directory.
An example `wmsConfig.xml` file is shipped with the TDS, which looks like:

{% capture rmd %}{% includefile ../tds/src/main/webapp/WEB-INF/altContent/startup/wmsConfig.xml %}{% endcapture %}
{% capture rmd %}{% includefile ../../../../tds/src/main/webapp/WEB-INF/altContent/startup/wmsConfig.xml %}{% endcapture %}

~~~xml
{{ rmd }}
Expand Down
1 change: 0 additions & 1 deletion gradle/any/shared-mvn-coords.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ ext {
buildPlugins.spotless = 'com.diffplug.spotless:spotless-plugin-gradle:4.5.1'
buildPlugins.protobuf = 'com.google.protobuf:protobuf-gradle-plugin:0.8.18'
buildPlugins.nexus = 'edu.ucar.unidata:unidata-nexus-gradle:0.0.1'
buildPlugins.jekyll = 'edu.ucar.unidata.site:jekyll-plugin:0.0.4'
buildPlugins.depcheck = 'org.owasp:dependency-check-gradle:8.2.1'

// slf4j version is declared in a place where we cannot use the tds-platform project to handle resolving versions
Expand Down
94 changes: 94 additions & 0 deletions project-files/jenkins/pipelines/docs
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
pipeline {
agent { label 'main' }
stages {
stage('Bootstrap 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 {
sh '''#!/bin/bash -l
select-java temurin 17
./gradlew :docs:copySharedJekyllFiles
'''
}
}
stage('Build adminguide') {
steps {
sh '''docker run --rm \
-e SRC_DIR=/tds/docs/adminguide/src/site \
-e DOCS_UID=$(id -u) \
-v .:/tds \
-v ./docs/build/site/adminguide:/site \
docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4 build
'''
}
}
stage('Build devguide') {
steps {
sh '''docker run --rm \
-e SRC_DIR=/tds/docs/devguide/src/site \
-e DOCS_UID=$(id -u) \
-v .:/tds \
-v ./docs/build/site/devguide:/site \
docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4 build
'''
}
}
stage('Build quickstart') {
steps {
sh '''docker run --rm \
-e SRC_DIR=/tds/docs/quickstart/src/site \
-e DOCS_UID=$(id -u) \
-v .:/tds \
-v ./docs/build/site/quickstart:/site \
docker.unidata.ucar.edu/unidata-jekyll-docs:0.0.4 build
'''
}
}
stage('Build userguide') {
steps {
sh '''docker run --rm \
-e SRC_DIR=/tds/docs/userguide/src/site \
-e DOCS_UID=$(id -u) \
-v .:/tds \
-v ./docs/build/site/userguide:/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 17
set +x
./gradlew \
-Pnexus.username=`get_pw NEXUS_USER` \
-Pnexus.password=`get_pw NEXUS_PW` \
-x :docs:buildAdminGuide \
-x :docs:buildDevGuide \
-x :docs:buildQuickstart \
-x :docs:buildUserGuide \
-x :docs:buildAllJekyllSites \
:docs:publishAllJekyllSitesAsVersioned
'''
}
}
}
}
}

0 comments on commit 5ce926d

Please sign in to comment.