Publish database-free documentation directly through GitHub Pages

.github/scripts/check-site.R

@@ -0,0 +1,19 @@
+# Run after pkgdown builds the site; fail before uploading a stale version.
+args <- commandArgs(trailingOnly = TRUE)
+site <- if (length(args)) args[[1]] else "docs"
+metadata <- read.dcf("DESCRIPTION")
+version <- unname(metadata[1, "Version"])
+index <- file.path(site, "index.html")
+if (!file.exists(index)) stop("Missing site homepage: ", index)
+html <- xml2::read_html(index)
+node <- xml2::xml_find_first(html, "//nav//small[contains(@class, 'nav-text')]")
+actual <- trimws(xml2::xml_text(node))
+if (is.na(actual) || !identical(actual, version)) {
+  stop("Website version ", actual, " differs from DESCRIPTION version ", version)
+}
+text <- xml2::xml_text(html)
+claims <- regmatches(text, gregexpr("R package version [0-9]+\\.[0-9]+\\.[0-9]+", text))[[1]]
+if (length(claims) && any(sub("R package version ", "", claims, fixed = TRUE) != version)) {
+  stop("The homepage contains a stale package-version statement or citation.")
+}
+message("Website version verified: ", metadata[1, "Package"], " ", version)

.github/workflows/pkgdown.yaml

@@ -3,8 +3,6 @@ name: pkgdown
 on:
   push:
     branches: [master]
-    paths-ignore:
-      - docs/**
   pull_request:
     branches: [master]
   workflow_dispatch:
@@ -19,50 +17,42 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: r-lib/actions/setup-pandoc@v2
       - uses: r-lib/actions/setup-r@v2
         with:
           use-public-rspm: true
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::pkgdown, local::.
+          extra-packages: any::pkgdown, any::rmarkdown, any::xml2, any::pkgload, local::.
           needs: website
+      - name: Refresh README from current source metadata
+        run: rmarkdown::render("README.Rmd", output_file = "README.md", quiet = TRUE)
+        shell: Rscript {0}
       - name: Build site
-        # Runnable examples use local metadata/path helpers only. Network-using
-        # Biotic download and reference-data functions have no runnable examples.
         run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
         shell: Rscript {0}
-      - name: Upload site artifact
-        uses: actions/upload-artifact@v4
+      - name: Verify published package version
+        run: Rscript .github/scripts/check-site.R
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
         with:
-          name: pkgdown-site
           path: docs
-          if-no-files-found: error
-          retention-days: 1
 
   deploy:
     if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
     needs: build
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: master
-      - name: Download site artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: pkgdown-site
-          path: site
-      - name: Deploy to existing Pages folder
-        uses: JamesIves/github-pages-deploy-action@v4.5.0
-        with:
-          branch: master
-          folder: site
-          target-folder: docs
-          clean: true
+      - name: Deploy the validated artifact
+        id: deployment
+        uses: actions/deploy-pages@v5

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: BioticExplorerServer
 Type: Package
 Title: R Package for Downloading Server-Side Data for BioticExplorer
-Version: 0.8.11
-Date: 2026-10-25
+Version: 0.8.13
+Date: 2026-10-26
 Authors@R: c(person("Mikko", "Vihtakari", email = "mikko.vihtakari@hi.no",
                   role = c("aut", "cre")), 
           person("Ibrahim", "Umar",

NEWS.md

@@ -1,3 +1,11 @@
+# BioticExplorerServer 0.8.13
+
+* Retain the published station-count illustration while rendering database examples as code only.
+
+# BioticExplorerServer 0.8.12
+
+* Publish pkgdown directly through GitHub Pages artifacts, with source-version verification and no generated commits.
+
 # BioticExplorerServer 0.8.11
 
 * Declare the upstream GitHub source for RstoxData so clean installations and CI can resolve the dependency.

README.Rmd

@@ -7,8 +7,7 @@ editor_options:
 ---
 
 ```{r, include = FALSE}
-knitr::opts_chunk$set(fig.path = "man/figures/README-")
-suppressPackageStartupMessages(library(tidyverse))
+knitr::opts_chunk$set(fig.path = "man/figures/README-", eval = FALSE)
 ```
 
 
@@ -27,6 +26,8 @@ See the [package website](https://deepwaterimr.github.io/BioticExplorerServer/)
 remotes::install_github("DeepWaterIMR/BioticExplorerServer")
 ```
 
+The database examples below are shown as code and are not executed while building this documentation.
+
 ## Usage
 
 ### Download the IMR biotic database
@@ -152,6 +153,8 @@ stnall %>%
   )
 ```
 
+![Figure 1. Historical example of station counts by year, retained from the previously published documentation. Re-run the code above against your local database for current results.](man/figures/README-unnamed-chunk-9-1.png)
+
 The duckdb database contains following data tables:
 
 ```{r}

README.md

@@ -22,6 +22,9 @@ documentation and function reference.
 remotes::install_github("DeepWaterIMR/BioticExplorerServer")
 ```
 
+The database examples below are shown as code and are not executed while
+building this documentation.
+
 ## Usage
 
 ### Download the IMR biotic database
@@ -53,7 +56,17 @@ library(BioticExplorerServer)
 compileDatabase() # writes to defaultDbPath(); pass dbPath to choose another folder
 ```
 
-**Where the database goes.** The default `dbPath` is `~/IMR_biotic_BES_database` on macOS and Linux. On Windows R expands `~` through the Documents special folder, which OneDrive's Known Folder Move often redirects into a synchronized `OneDrive - <Organization>\Documents` folder — the last place a multi-gigabyte database should live. Since version 0.8.7 the default therefore resolves to `%USERPROFILE%\IMR_biotic_BES_database` on Windows, matching the convention documented by [BAIT](https://github.com/DeepWaterIMR/BAIT). Call `defaultDbPath()` to see the resolved path, and `findDatabase()` to locate a database that an earlier version installed under Documents.
+**Where the database goes.** The default `dbPath` is
+`~/IMR_biotic_BES_database` on macOS and Linux. On Windows R expands `~`
+through the Documents special folder, which OneDrive’s Known Folder Move
+often redirects into a synchronized
+`OneDrive - <Organization>\Documents` folder — the last place a
+multi-gigabyte database should live. Since version 0.8.7 the default
+therefore resolves to `%USERPROFILE%\IMR_biotic_BES_database` on
+Windows, matching the convention documented by
+[BAIT](https://github.com/DeepWaterIMR/BAIT). Call `defaultDbPath()` to
+see the resolved path, and `findDatabase()` to locate a database that an
+earlier version installed under Documents.
 
 ### Update the database
 
@@ -113,11 +126,7 @@ if (any(installed_packages == FALSE)) {
 
 # Load the packages
 invisible(lapply(packages, library, character.only = TRUE, quietly = TRUE))
-```
-
-    ## Warning: package 'duckdb' was built under R version 4.6.1
 
-``` r
 # Connect to the database (assuming you used standard dbPath and name)
 con_db <- BioticExplorerServer::findDatabase() %>% 
   duckdb::duckdb(read_only = TRUE) %>% 
@@ -146,19 +155,6 @@ mission %>%
   collect()
 ```
 
-    ## # A tibble: 6 × 14
-    ##   startyear platformname               cruise missiontype platform missionnumber
-    ##       <int> <chr>                      <chr>  <chr>       <chr>            <int>
-    ## 1      1906 NVG-sampling (Norsk vårgy… <NA>   1           10016                1
-    ## 2      1907 NVG-sampling (Norsk vårgy… <NA>   1           10016                1
-    ## 3      1908 NVG-sampling (Norsk vårgy… <NA>   1           10016                1
-    ## 4      1909 NVG-sampling (Norsk vårgy… <NA>   1           10016                1
-    ## 5      1910 NVG-sampling (Norsk vårgy… <NA>   1           10016                1
-    ## 6      1911 NVG-sampling (Norsk vårgy… <NA>   1           10016                1
-    ## # ℹ 8 more variables: missiontypename <chr>, callsignal <chr>,
-    ## #   missionstartdate <chr>, missionstopdate <chr>, purpose <chr>,
-    ## #   missionid <chr>, cruiseseriescode <chr>, idCruiseseriesSample <chr>
-
 The [dplyr package can also be used with
 databases](https://solutions.posit.co/connections/db/r-packages/dplyr/).
 The only difference from normal use is that you’ll need to
@@ -209,28 +205,21 @@ stnall %>%
   )
 ```
 
-<div class="figure">
-
-<img src="man/figures/README-unnamed-chunk-9-1.png" alt="Figure 1. Number of IMR Biotic sampling stations per year from around 1914 to present. Zero catch stations (is.na(commonname)) are shown in red, while stations with positive catches are shown in grey."  />
-<p class="caption">
-
-Figure 1. Number of IMR Biotic sampling stations per year from around
-1914 to present. Zero catch stations (is.na(commonname)) are shown in
-red, while stations with positive catches are shown in grey.
-</p>
-
-</div>
+<figure>
+<img src="man/figures/README-unnamed-chunk-9-1.png"
+alt="Figure 1. Historical example of station counts by year, retained from the previously published documentation. Re-run the code above against your local database for current results." />
+<figcaption aria-hidden="true">Figure 1. Historical example of station
+counts by year, retained from the previously published documentation.
+Re-run the code above against your local database for current
+results.</figcaption>
+</figure>
 
 The duckdb database contains following data tables:
 
 ``` r
 DBI::dbListTables(con_db)
 ```
 
-    ##  [1] "ageall"          "codeindex"       "csindex"         "filesize"       
-    ##  [5] "gearindex"       "indall"          "metadata"        "mission"        
-    ##  [9] "source_manifest" "stnall"          "taxaindex"
-
 `source_manifest`, created by `updateDatabase()`, stores metadata-only
 change signals used to identify which years need refreshing.