Merge pull request '📖 Add OBITools documentation (obidoc) management and update Hugo to 0.159.2' (#10) from push-usnlqwzstwtw into master

Reviewed-on: #10

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:

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" ;; \

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