Live site: https://bayesian-graphical-modelling-lab.github.io/bgms/
Documentation site for the bgms R package.
guide/— User's Guide (tutorials, statistical concepts)examples/— Worked analyses (one analysis per page, code and workflow)reference/— Function reference (API documentation)manual/— Reference Manual (C++ backend, algorithms)
Requires Quarto.
# Preview with live reload
quarto preview
# Build static site
quarto renderOutput goes to docs/.
The GNUmakefile wraps the builds that need more than a bare quarto render,
and takes QUARTO= if Quarto is not on your PATH (the RStudio-bundled binary
lives under /Applications/RStudio.app/Contents/Resources/app/quarto/bin). It
is named GNUmakefile, not Makefile, on purpose: make reads it either way,
but a file named Makefile in the repo root makes RStudio classify the project
as a Makefile project and replace the Quarto build UI (see below).
make site # render the whole site with the ci profile
make fixtures # rebake the .rds fixtures (about ten minutes)
make example-scripts # regenerate the Examples companion scripts
make examples-pdf # the Examples series as one PDFbgms-docs.Rproj deliberately carries no BuildType line. RStudio then
detects the Quarto project from _quarto.yml and offers its Build Website
button, which renders and opens a local preview. Do not set a build type in
Tools > Project Options > Build Tools: choosing Makefile there replaces the
Quarto build UI with a bare make run that shows no preview.
A bare render does not set R_LIBS or the profile, so put both in a
.Renviron in the repo root (untracked, already gitignored) and restart the R
session:
R_LIBS=dev/lib-bgms-develop
QUARTO_PROFILE=ci
With that in place the Build Website button renders against the documented
bgms build with the ci profile, matching what CI publishes. The GNUmakefile
targets remain the terminal equivalents, and are still the only way to build
the Examples PDF.
examples/ holds the worked analyses. Two of its build steps are generated,
never hand-maintained:
- Companion scripts. Each page's code is tangled to
examples/R/NN-slug.Rbyscripts/extract-example-code.R, which runs as the projectpre-renderstep, so the script published beside a page always matches it. The scripts are gitignored build artifacts. - The PDF.
make examples-pdfrenders the index and every published example page, in series order, into one PDF and copies it todocs/examples/bgms-worked-analyses.pdf. It uses thepdfQuarto profile (_quarto-pdf.yml), writes to_pdf/, and leaves the site render alone. Run it after the site render, which rewritesdocs/;make alldoes both in that order.
The series order lives in scripts/examples-series.R. See STYLE_GUIDE.md
§ Example Pages for the page shape and the chunk conventions the two steps
rely on.
Pages that report model output read baked .rds fixtures instead of refitting.
The fixtures are not in the repository; bake them once, pointing R at the bgms
build you want the numbers to come from:
R_LIBS=dev/lib-bgms-develop Rscript fixtures/bake.Rfixtures/bake.R is the only fixture script. Rebake whenever the bgms version
changes, then re-render so the summaries, figures, and prose numbers stay in
sync with the package.
The Wenchuan fit and its prior sensitivity check run at the tutorial paper's
configuration, so the site and the paper quote one set of numbers rather than
two compatible ones. That costs about ten minutes of baking and roughly 160 MB
of .rds on disk (gitignored). Everything else in the script runs at package
defaults. See the header of fixtures/bake.R for the reasoning and the
measured per-fixture timings.
- Edit
.qmdfiles in the appropriate directory - Preview locally with
quarto preview - Commit and push — GitHub Actions will deploy automatically
The canonical site is https://bayesian-graphical-modelling-lab.github.io/bgms/,
which is GitHub Pages for the bgms package repository. This repository owns
the content; the package repository owns the URL.
.github/workflows/publish.yml renders the
site here and publishes it to the gh-pages branch of
Bayesian-Graphical-Modelling-Lab/bgms.
The documentation is versioned, so that branch holds more than one site:
| Path | What it is | Deployed by |
|---|---|---|
/ |
the current release | every push to main |
/dev/ |
the development documentation | every push to docs/develop |
/vX.Y.Z/ |
a frozen archive of a past release | by hand on release day, starting with the release after 0.2.0.0 |
Every deploy step is guarded on a branch, so a manual run from any other branch
renders and stops. A push to docs/develop publishes to /dev/ straight away:
that documentation is public, and every page of it says so.
A root deploy must never touch dev/ or any vX.Y.Z/. It replaces the
root, deleting whatever the render no longer produces, and leaves the other
sites alone. A dev deploy is the mirror image: it replaces dev/ and reads or
writes nothing outside it.
peaceiris/actions-gh-pages cannot express that. It cleans its destination with
git rm -r --ignore-unmatch * before copying, and with no destination_dir the
destination is the whole branch, which would take dev/ and every archive with
it; exclude_assets filters the source, not the destination. So both deploys to
the bgms repository go through
scripts/deploy-gh-pages.sh, which clears the
root by name and keeps .git, dev/, and any vX.Y.Z/ directory. Its header
carries the reasoning.
scripts/simulate-deploy.sh proves both
directions against a throwaway repository holding a released site, a dev/
build, and a v0.1.0/ archive. It needs no network and no credentials. Run it
after any change to the deploy script:
scripts/simulate-deploy.shOne environment variable, BGMS_DOC_CHANNEL, tells a render which of the two
sites it is: release (the default) or dev. Everything that differs hangs off
it, through scripts/doc-build.R:
- The version the citation picker prints is read from the installed bgms
DESCRIPTION, never written down in a page. The release job installs bgms from
the package's
mainbranch and the dev job fromdevelop, so each build stamps what it documents.BGMS_DOC_VERSIONoverrides it if a render ever has to claim another version. versions.json, the version index at the site root, is written byscripts/versions.Rand only by the release build: it describes the whole family, and only the build that owns the root can speak for the family. The dev build reads the root copy one directory up.- The navbar version switcher is built from that file by the script in
js.html. If the file is missing, as in a local preview, there is no dropdown and nothing else changes. - A dev build is marked as one by
scripts/dev-build.R: a dismissable banner on every page,<meta name="robots" content="noindex">, and a canonical link to the same page under the site root, so search traffic collects on the release docs. It also dropssitemap.xmlandrobots.txt, which describe the root's URLs and not its own. A release render gets none of this.
To see a development build locally:
BGMS_DOC_CHANNEL=dev make siteThe order matters, because the root deploy overwrites the outgoing release.
-
Archive the outgoing release first (from the release after 0.2.0.0 onwards; there is nothing to archive at 0.2.0.0). In a clone of the bgms repository, on
gh-pages, copy the root into its version directory and push:mkdir vX.Y.Z rsync -a --exclude '/.git/' --exclude '/dev/' --exclude '/v[0-9]*/' ./ vX.Y.Z/ git add vX.Y.Z && git commit -m "Archive the X.Y.Z documentation" && git push
The copy keeps the
versions.jsonit was built with. That is harmless: the switcher notices the file belongs to the root and reloads the live one. -
Add the archived version to
ARCHIVEDinscripts/versions.R, one line, newest first. -
Merge
docs/developintomainand push. The push renders and deploys the root, which now also publishes the newversions.json. -
Verify: the root serves the new release,
/dev/is still there and still intact, the switcher lists every entry, and the archived version still answers at/vX.Y.Z/.
This repository's own Pages site,
https://bayesian-graphical-modelling-lab.github.io/bgms-docs/, serves only
the redirect in redirect/: index.html sends the root to the
canonical address, and 404.html carries any deep path across to the matching
canonical path.
scripts/redirects.R runs as the project post-render step and writes a stub
for every URL the earlier pkgdown site served, so old links and indexed URLs
land on the page that now owns the material instead of a 404. Add mappings to
the table at the top of that script; it checks every target against the render
output and warns about any that are missing.
The cross-repository deploy needs an SSH deploy key. This is the only part that cannot be done from this repository:
- Generate a key pair, for example
ssh-keygen -t ed25519 -N "" -C "bgms-docs site deploy" -f bgms-site-deploy - In the bgms repository: Settings → Deploy keys → Add deploy key. Paste
bgms-site-deploy.pub, title it "bgms-docs site deploy", and check Allow write access. - In this repository: Settings → Secrets and variables → Actions → New
repository secret, named
BGMS_SITE_DEPLOY_KEY, holding the contents of the private keybgms-site-deploy. - In the bgms repository: Settings → Pages → Source "Deploy from a
branch", branch
gh-pages, folder/ (root). - In the bgms repository, retire pkgdown before the first deploy, or the
next push there rebuilds pkgdown over this site: delete
.github/workflows/pkgdown.yamland_pkgdown.yml. - Delete the local key pair once both halves are stored.
The deploy replaces the published file set but keeps the gh-pages history, so
a bad deploy can be undone two ways:
- Re-run the workflow from the last good commit (Actions → Build and Deploy Documentation → Run workflow), or
- revert the offending commit on
mainand let the push deploy.
To inspect what is live, check out gh-pages in a clone of the bgms
repository.
Documentation content is licensed under CC BY 4.0.
Site theme files (theme.scss, theme-dark.scss, index.css, js.html, filters/) were adapted from the quarto-dev/quarto-web project (MIT License, Copyright © 2022 Posit Software, PBC).