From 6007320202fc7d6d0c077531471d560a63e5de4e Mon Sep 17 00:00:00 2001 From: Matthijs Berends Date: Mon, 16 Nov 2026 10:12:04 +0100 Subject: [PATCH] (v3.1.0.9023) Publish the reference of every released version as Markdown at amr-for-r.org/release// for LLMs, and keep it when deploying the website --- .github/scripts/build_release_reference.R | 141 ++++++++++++++++++++++ .github/workflows/website-release.yaml | 109 +++++++++++++++++ .github/workflows/website.yaml | 27 ++++- DESCRIPTION | 4 +- NEWS.md | 2 +- 5 files changed, 277 insertions(+), 6 deletions(-) create mode 100644 .github/scripts/build_release_reference.R create mode 100644 .github/workflows/website-release.yaml diff --git a/.github/scripts/build_release_reference.R b/.github/scripts/build_release_reference.R new file mode 100644 index 000000000..3c2c2e9b8 --- /dev/null +++ b/.github/scripts/build_release_reference.R @@ -0,0 +1,141 @@ +# ==================================================================== # +# TITLE: # +# AMR: An R Package for Working with Antimicrobial Resistance Data # +# # +# SOURCE CODE: # +# https://github.com/msberends/AMR # +# # +# PLEASE CITE THIS SOFTWARE AS: # +# Berends MS, Luz CF, Friedrich AW, et al. (2022). # +# AMR: An R Package for Working with Antimicrobial Resistance Data. # +# Journal of Statistical Software, 104(3), 1-31. # +# https://doi.org/10.18637/jss.v104.i03 # +# # +# Developed at the University of Groningen and the University Medical # +# Center Groningen in the Netherlands, in collaboration with many # +# colleagues from around the world, see our website. # +# # +# This R package is free software; you can freely use and distribute # +# it for both personal and commercial purposes under the terms of the # +# GNU General Public License version 2.0 (GNU GPL-2), as published by # +# the Free Software Foundation. # +# We created this package for both routine data analysis and academic # +# research and it was publicly released in the hope that it will be # +# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY. # +# # +# Visit our website for the full manual and a complete tutorial about # +# how to conduct AMR data analysis: https://amr-for-r.org # +# ==================================================================== # + +# Build the function and data set reference of one released AMR version as Markdown only, for use by LLMs, at https://amr-for-r.org/release//. +# Used by .github/workflows/website-release.yaml, after installing AMR from the release tag: +# Rscript build_release_reference.R +# Writes /release//reference/*.md and /release//llms.txt, and regenerates the version index /release/llms.txt. +# The HTML pages that pkgdown renders are only an intermediate step and are not published, so the main website remains the only human-readable reference. + +args <- commandArgs(trailingOnly = TRUE) +if (length(args) != 3) { + stop("Usage: Rscript build_release_reference.R ") +} +src <- normalizePath(args[1], mustWork = TRUE) +site <- normalizePath(args[2], mustWork = TRUE) +version <- args[3] +if (!grepl("^[0-9]+[.][0-9]+[.][0-9]+$", version)) { + stop("Version must be a released version such as 3.1.0, not '", version, "'") +} + +desc <- read.dcf(file.path(src, "DESCRIPTION")) +if (desc[1, "Version"] != version) { + stop("The package source has version ", desc[1, "Version"], ", not ", version) +} +release_date <- if ("Date" %in% colnames(desc)) desc[1, "Date"] else NA_character_ + +base_url <- paste0("https://amr-for-r.org/release/", version) +html_dir <- file.path(tempfile("pkgdown_"), version) +release_root <- file.path(site, "release") +out_dir <- file.path(release_root, version) + +# render the reference as HTML in a temporary folder, without running examples +pkg <- pkgdown::as_pkgdown(src, override = list(destination = html_dir, url = base_url)) +pkgdown::build_reference(pkg, examples = FALSE, lazy = FALSE, devel = FALSE) + +# convert every HTML page to Markdown, with absolute links to the Markdown pages of this same version +unlink(out_dir, recursive = TRUE) +dir.create(file.path(out_dir, "reference"), recursive = TRUE) +html_files <- list.files(file.path(html_dir, "reference"), pattern = "[.]html$") +for (html_file in html_files) { + pkgdown:::convert_md( + src_path = file.path(html_dir, "reference", html_file), + dst_path = file.path(out_dir, "reference", sub("[.]html$", ".md", html_file)), + url = paste0(base_url, "/reference/", html_file) + ) +} +md_files <- list.files(file.path(out_dir, "reference"), pattern = "[.]md$") +if (length(md_files) != length(html_files) || !"index.md" %in% md_files) { + stop("Converting HTML to Markdown failed: ", length(html_files), " HTML pages, ", length(md_files), " Markdown pages") +} +unlink(dirname(html_dir), recursive = TRUE) + +# llms.txt of this version: a header that states the version, followed by the reference index +index_md <- readLines(file.path(out_dir, "reference", "index.md"), encoding = "UTF-8") +index_md <- index_md[-1] # drop the '# Package index' title, the header below replaces it +index_md <- index_md[cumsum(index_md != "") > 0] # and the blank lines that followed it +writeLines( + c( + paste0("# AMR for R ", version, ": reference of all functions and data sets"), + "", + paste0( + "> This is the complete reference documentation of version ", version, " of the AMR package for R", + if (!is.na(release_date)) paste0(", released on ", release_date) else "", + ". It applies to AMR ", version, " only: functions, arguments, defaults, data sets and their columns can differ in other versions." + ), + "", + "How to use this reference:", + "", + paste0("- Every function and data set has its own page, linked below. The pages are Markdown and live at `", base_url, "/reference/.md`."), + "- Each page contains the usage (all arguments with their defaults), the description of every argument, details, the return value and examples.", + "- Several related functions share one page; the list below shows which page documents which function (e.g., `mo_gramstain()` is documented on `mo_property.md`).", + "- A function or argument that is not in this reference does not exist in this version.", + "- The documentation of other versions is listed at .", + "", + index_md + ), + file.path(out_dir, "llms.txt"), + useBytes = TRUE +) + +# regenerate the version index from all versions present in the gh-pages checkout +versions <- list.files(release_root, pattern = "^[0-9]+[.][0-9]+[.][0-9]+$") +versions <- versions[file.exists(file.path(release_root, versions, "llms.txt"))] +versions <- versions[order(numeric_version(versions), decreasing = TRUE)] +version_dates <- vapply( + versions, + function(v) { + first_lines <- readLines(file.path(release_root, v, "llms.txt"), n = 3, encoding = "UTF-8") + date <- regmatches(first_lines, regexpr("released on [0-9]{4}-[0-9]{2}-[0-9]{2}", first_lines)) + if (length(date) == 0) "" else paste0(", ", date[1]) + }, + character(1) +) +writeLines( + c( + "# AMR for R: reference documentation per package version", + "", + "> The AMR package for R changes between versions: functions, arguments, defaults, data sets and clinical breakpoints are added or changed. Answers about AMR must therefore be based on the documentation of the version that the user has installed.", + "", + "How to find the right documentation:", + "", + "1. Determine the installed version, which is the output of `packageVersion(\"AMR\")` in R.", + "2. If the version has three numbers (e.g., `3.1.0`), it is a release from CRAN. Use the reference of exactly that version from the list below.", + "3. If the version has four numbers (e.g., `3.1.0.9022`), it is a development version from GitHub. Use the reference of the latest development version at .", + "4. If the installed version is not listed below, use the closest older version and state this.", + "", + "## Released versions", + "", + paste0("- [AMR ", versions, "](https://amr-for-r.org/release/", versions, "/llms.txt): reference of all functions and data sets", version_dates) + ), + file.path(release_root, "llms.txt"), + useBytes = TRUE +) + +message("Built the reference of AMR ", version, ": ", length(md_files), " Markdown pages in ", out_dir) diff --git a/.github/workflows/website-release.yaml b/.github/workflows/website-release.yaml new file mode 100644 index 000000000..4d3bbc2a9 --- /dev/null +++ b/.github/workflows/website-release.yaml @@ -0,0 +1,109 @@ +# ==================================================================== # +# TITLE: # +# AMR: An R Package for Working with Antimicrobial Resistance Data # +# # +# SOURCE CODE: # +# https://github.com/msberends/AMR # +# # +# PLEASE CITE THIS SOFTWARE AS: # +# Berends MS, Luz CF, Friedrich AW, et al. (2022). # +# AMR: An R Package for Working with Antimicrobial Resistance Data. # +# Journal of Statistical Software, 104(3), 1-31. # +# https://doi.org/10.18637/jss.v104.i03 # +# # +# Developed at the University of Groningen and the University Medical # +# Center Groningen in the Netherlands, in collaboration with many # +# colleagues from around the world, see our website. # +# # +# This R package is free software; you can freely use and distribute # +# it for both personal and commercial purposes under the terms of the # +# GNU General Public License version 2.0 (GNU GPL-2), as published by # +# the Free Software Foundation. # +# We created this package for both routine data analysis and academic # +# research and it was publicly released in the hope that it will be # +# useful, but it comes WITHOUT ANY WARRANTY OR LIABILITY. # +# # +# Visit our website for the full manual and a complete tutorial about # +# how to conduct AMR data analysis: https://amr-for-r.org # +# ==================================================================== # + +# Publish the reference of a released version as Markdown at https://amr-for-r.org/release//, for use by LLMs +# Runs when a GitHub release is published, or manually for an existing tag (e.g., to add older versions) +# The build script always comes from 'main', the documentation from the release tag + +on: + release: + types: [published] + workflow_dispatch: + inputs: + tag: + description: "Release tag to publish the reference of, e.g. v3.1.0" + required: true + type: string + +name: Publish release reference + +# website.yaml and website-release.yaml both push to the 'gh-pages' branch, so they must never run at the same time +concurrency: + group: gh-pages + cancel-in-progress: false + +jobs: + publish-release-reference: + runs-on: ubuntu-latest + env: + TAG: ${{ github.event.release.tag_name || inputs.tag }} + steps: + + - name: Checkout build script from main + uses: actions/checkout@v4 + with: + ref: main + path: main + + - name: Checkout package source of the release tag + uses: actions/checkout@v4 + with: + ref: ${{ env.TAG }} + path: pkg + + - name: Checkout gh-pages + uses: actions/checkout@v4 + with: + ref: gh-pages + path: site + + - uses: r-lib/actions/setup-pandoc@v2 + + - name: Set up R + uses: r-lib/actions/setup-r@v2 + with: + r-version: "release" + # use RStudio Package Manager (RSPM) to quickly install packages + use-public-rspm: true + + - name: Install pkgdown and the package from the release tag + uses: r-lib/actions/setup-r-dependencies@v2 + with: + working-directory: pkg + dependencies: '"hard"' + extra-packages: | + any::pkgdown + local::. + + - name: Build reference + run: | + Rscript main/.github/scripts/build_release_reference.R pkg site "${TAG#v}" + + - name: Push to gh-pages + run: | + cd site + git config user.name "github-actions" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add --all release + if git diff --cached --quiet; then + echo "No changes to the reference of $TAG" + else + git commit -m "Built release reference for AMR@${TAG#v}" + git push origin HEAD:gh-pages + fi diff --git a/.github/workflows/website.yaml b/.github/workflows/website.yaml index e5306ce9f..9a14b8e0a 100644 --- a/.github/workflows/website.yaml +++ b/.github/workflows/website.yaml @@ -28,7 +28,7 @@ # ==================================================================== # # Create a website from the R documentation using pkgdown -# Git commit and push to the 'gh-pages' branch +# Git commit and push to the 'gh-pages' branch, keeping the folder 'release' that website-release.yaml maintains on: push: @@ -37,6 +37,11 @@ on: name: Update website +# website.yaml and website-release.yaml both push to the 'gh-pages' branch, so they must never run at the same time +concurrency: + group: gh-pages + cancel-in-progress: false + jobs: update-website: runs-on: ubuntu-latest @@ -73,9 +78,25 @@ jobs: run: | rm vignettes/welcome_to_AMR.Rmd + - name: Build website + run: | + Rscript -e 'pkgdown::build_site_github_pages(dest_dir = "docs", clean = TRUE, install = TRUE, new_process = FALSE)' + # Send updates to repo using GH Actions bot - - name: Create website in separate branch + # pkgdown::deploy_to_branch() would delete everything on 'gh-pages' that this build did not create, including the + # folder 'release' with the reference per released version, so the build is copied over 'gh-pages' without that folder + - name: Deploy website to gh-pages branch, keeping the folder 'release' run: | git config user.name "github-actions" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - Rscript -e 'pkgdown::deploy_to_branch(new_process = FALSE, clean = TRUE, install = TRUE, branch = "gh-pages")' + git fetch origin gh-pages + git worktree add --detach "$RUNNER_TEMP/gh-pages" origin/gh-pages + rsync -a --delete --exclude '/.git' --exclude '/release/' docs/ "$RUNNER_TEMP/gh-pages/" + cd "$RUNNER_TEMP/gh-pages" + git add --all + if git diff --cached --quiet; then + echo "No changes to the website" + else + git commit -m "Built site for AMR@$(grep '^Version:' "$GITHUB_WORKSPACE/DESCRIPTION" | cut -d ' ' -f 2): ${GITHUB_SHA::7}" + git push origin HEAD:gh-pages + fi diff --git a/DESCRIPTION b/DESCRIPTION index afb462dcb..fb5a92a6d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: AMR -Version: 3.1.0.9022 -Date: 2026-11-14 +Version: 3.1.0.9023 +Date: 2026-11-16 Title: Antimicrobial Resistance Data Analysis Description: Functions to simplify and standardise antimicrobial resistance (AMR) data analysis and to work with microbial and antimicrobial properties by diff --git a/NEWS.md b/NEWS.md index 5bfade8e3..651d9293a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# AMR 3.1.0.9022 +# AMR 3.1.0.9023 This version fixes a critical bug in WISCA that biased all coverage estimates of `wisca()` and `antibiogram(..., wisca = TRUE)` downwards since AMR 3.0.0. Users are strongly advised to re-run their WISCA analyses.