From 3e95ad76f94fc673d873e2d95f6d3a633b382a62 Mon Sep 17 00:00:00 2001 From: Eric Coissac Date: Thu, 30 Apr 2026 20:02:40 +0200 Subject: [PATCH] :book: Add OBITools documentation (obidoc) management and update Hugo to 0.159.2 - Add new `--update-obidoc` and clarify existing ` --build_obodc` - Document obiDoc build process, first install & update workflow - Update Hugo version from 0.140.2 to 0.159.3 (extended for SCSS) - Add `golang-go` dependency to builder image - Enhance obidoc build command: add --gc, minify and draft support --- Readme.md | 45 +++++++++++++++++++++++++++++++- obijupyterhub/Dockerfile.builder | 3 ++- start-jupyterhub.sh | 20 ++++++++++++-- 3 files changed, 64 insertions(+), 4 deletions(-) diff --git a/Readme.md b/Readme.md index e779c24..5b8538a 100644 --- a/Readme.md +++ b/Readme.md @@ -82,7 +82,8 @@ These flags work alongside any mode: |------|--------| | `--stop-server` | Stop the stack and remove student containers, then exit | | `--update-lectures` | Rebuild the course website only (no Docker stop/start) | -| `--build-obidoc` | Force rebuild of the obidoc documentation | +| `--update-obidoc` | Rebuild the obidoc documentation only (no Docker stop/start) | +| `--build-obidoc` | Force rebuild of obidoc documentation on next full start | ## Installation and first run @@ -156,6 +157,48 @@ Packages are cached in `jupyterhub_volumes/builder/R_packages/`: - **Non-CRAN packages**: packages installed via `remotes::install_git()` or `remotes::install_github()` in your `.qmd` files are detected and pre-installed automatically before rendering. - **Clear the cache**: delete `jupyterhub_volumes/builder/R_packages/` to force a full reinstall. +## OBITools documentation (obidoc) + +The OBITools4 documentation is built from the [`obitools4-doc`](https://github.com/metabarcoding/obitools4-doc) repository using Hugo and served as a static site at `http://localhost:8888/obidoc/`. + +### How it works + +The builder container clones the repository (with all submodules), runs `hugo build`, and writes the generated HTML into `jupyterhub_volumes/web/obidoc/`. Caddy then serves these files directly — no special routing is needed. + +### First installation + +The documentation is built automatically on the first full start if `jupyterhub_volumes/web/obidoc/` is empty: + +```bash +./start-jupyterhub.sh +``` + +To force a build even if the directory is already populated, use `--build-obidoc` during a full start: + +```bash +./start-jupyterhub.sh --build-obidoc +``` + +### Updating the documentation + +To rebuild the documentation without stopping the running stack: + +```bash +./start-jupyterhub.sh --update-obidoc +``` + +This pulls the latest version of the builder image (or uses the local one with `--local-build`), reclones the `obitools4-doc` repository, rebuilds the site, and replaces the contents of `jupyterhub_volumes/web/obidoc/`. The JupyterHub stack keeps running throughout. + +### Removing the documentation + +To remove the built documentation (e.g. to free disk space or force a clean rebuild): + +```bash +rm -rf jupyterhub_volumes/web/obidoc/* +``` + +The next `./start-jupyterhub.sh` will rebuild it automatically. + ## Managing course and student data Each student lands in `/home/jovyan/work/` with three areas: diff --git a/obijupyterhub/Dockerfile.builder b/obijupyterhub/Dockerfile.builder index f6c0c9c..febc3b0 100644 --- a/obijupyterhub/Dockerfile.builder +++ b/obijupyterhub/Dockerfile.builder @@ -33,6 +33,7 @@ RUN apt-get update \ libtiff5-dev \ libjpeg-dev \ libuv1-dev \ + golang-go \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* @@ -44,7 +45,7 @@ RUN mkdir -p ${R_LIBS_BUILDER} \ # Install Hugo (extended version for SCSS support) # Detect architecture and download appropriate binary -ARG HUGO_VERSION=0.140.2 +ARG HUGO_VERSION=0.159.2 RUN ARCH=$(dpkg --print-architecture) \ && case "$ARCH" in \ amd64) HUGO_ARCH="amd64" ;; \ diff --git a/start-jupyterhub.sh b/start-jupyterhub.sh index c9cc42c..54193b4 100755 --- a/start-jupyterhub.sh +++ b/start-jupyterhub.sh @@ -38,6 +38,7 @@ REBUILD_HUB=false # Actions STOP_SERVER=false UPDATE_LECTURES=false +UPDATE_OBIDOC=false BUILD_OBIDOC=false usage() { @@ -58,7 +59,8 @@ Build options (--local-build only): Actions: --stop-server Stop the stack and remove student containers, then exit --update-lectures Rebuild the course website only (no Docker stop/start) - --build-obidoc Force rebuild of obidoc documentation + --update-obidoc Rebuild the obidoc documentation only (no Docker stop/start) + --build-obidoc Force rebuild of obidoc documentation on next full start -h, --help Show this help EOF } @@ -76,6 +78,7 @@ while [[ $# -gt 0 ]]; do --rebuild-hub) REBUILD_HUB=true; LOCAL_BUILD=true ;; --stop-server) STOP_SERVER=true ;; --update-lectures) UPDATE_LECTURES=true ;; + --update-obidoc) UPDATE_OBIDOC=true ;; --build-obidoc) BUILD_OBIDOC=true ;; -h|--help) usage; exit 0 ;; *) echo "Unknown option: $1" >&2; usage; exit 1 ;; @@ -387,7 +390,7 @@ build_obidoc() { -j 8 \ https://github.com/metabarcoding/obitools4-doc.git cd obitools4-doc - hugo -D build --baseURL "/obidoc/" + hugo --gc --minify --buildDrafts --baseURL "/obidoc/" mkdir -p /workspace/jupyterhub_volumes/web/obidoc rm -rf /workspace/jupyterhub_volumes/web/obidoc/* mv public/* /workspace/jupyterhub_volumes/web/obidoc/ @@ -498,6 +501,19 @@ if $UPDATE_LECTURES; then exit 0 fi +if $UPDATE_OBIDOC; then + if $LOCAL_BUILD; then + build_builder_image + elif ! $NO_BUILD; then + docker pull "$BUILDER_IMAGE" 2>/dev/null \ + || echo -e "${YELLOW}Could not pull builder image, using local cache.${NC}" + fi + BUILD_OBIDOC=true + build_obidoc + popd >/dev/null + exit 0 +fi + stop_stack if $PUBLISH; then