Docs Build and Deploy

Purpose

Describe how the DSAMbayes documentation site is built, previewed, and deployed.

Documentation layers

DSAMbayes currently has two documentation layers with distinct purposes:

1. Package reference inputs

Package reference content is generated from:

  • roxygen comments in R/
  • vignettes in vignettes/
  • generated man/*.Rd files

This material supports package help pages and package-check workflows. It is not the deployed public docs site.

2. Public documentation site

The public docs site is built from hand-authored Markdown under docs/ plus the Hugo/Relearn wrapper under docs-site/.

Build locally:

python3 docs-site/build_content.py
(cd docs-site && hugo --cleanDestinationDir)

Build flow:

  1. docs/ is the source of truth.
  2. docs-site/build_content.py mirrors and normalizes content into docs-site/content/.
  3. Hugo renders the final site into docs-site/public/ and cleans removed pages from prior builds.

There is no canonical automated deployment pipeline for the public docs site. Build and publish manually if you choose to host updated docs.

Preview locally:

  • open Markdown files directly for quick edits, or
  • serve/build the Hugo site for full navigation and theme rendering

If you maintain an external published mirror such as https://dsambayes.docs.wppma.space/, treat it as a manual distribution channel that may lag the repository. Verify freshness before linking to it in release communication.

Configuration

docs/docs-config.json defines:

  • metadata — site name, description, version.
  • branding — logo, favicon, primary colour.
  • navigation — navbar links and sidebar structure.
  • features — math rendering (enabled), search (local).

Adding a new page

  1. Create the Markdown file in the appropriate section directory (e.g. docs/modelling/new-page.md).
  2. Add a sidebar entry in docs/docs-config.json under the appropriate section.
  3. Add a row to the section’s index.md page table.
  4. Update docs/_plan/content-map.md if tracking authoring status.