StochTree Documentation Source Code and Build Workflows

Building the Docs Locally

MacOS

Software dependencies

You'll need to have the following software installed

• Python: can be installed via homebrew, conda, and directly from the python site
• R: can be installed via CRAN or homebrew
• Quarto: can be installed directly from the Quarto site or homebrew
• Doxygen: can be installed directly from the Doxygen site or homebrew

Setting up R and Python build dependencies

Building multi-lingual (R and Python) vignettes requires installing the vignettes' package dependencies. In Python, this is done via a virtual environment (local .venv)

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install git+https://github.com/StochasticTree/stochtree.git

And in R, this is typically done as a global system install, though you might also consider renv for managing project-specific R dependencies

Rscript -e 'install.packages(c("remotes", "devtools", "roxygen2", "ggplot2", "latex2exp", "decor", "pkgdown", "cpp11", "BH", "doParallel", "foreach", "knitr", "Matrix", "MASS", "mvtnorm", "rmarkdown", "testthat", "tgp", "here", "reticulate"), repos="https://cloud.r-project.org/")'
Rscript -e 'remotes::install_github("StochasticTree/stochtree", ref = "r-dev")'

Cloning the stochtree repo

Building the R API docs (roxygen2 / pkgdown) and C++ API docs (Doxygen) requires the stochtree source. Clone it into stochtree_repo/ at the repo root:

git clone --recurse-submodules https://github.com/StochasticTree/stochtree.git stochtree_repo

Building the pkgdown site for the R API

With the stochtree repo checked out and R dependencies installed (see above), run:

cd stochtree_repo
Rscript cran-bootstrap.R 0 1 0
cd ..
mkdir -p docs/R_docs/pkgdown
Rscript -e 'pkgdown::build_site_github_pages("stochtree_repo/stochtree_cran", dest_dir = "../../docs/R_docs/pkgdown", install = TRUE)'
cd stochtree_repo
Rscript cran-cleanup.R
cd ..

cran-bootstrap.R 0 1 0 prepares a stochtree_cran/ subdirectory with the pkgdown config but without vignette source (vignettes are served by the Quarto site instead). cran-cleanup.R removes that temporary directory when done. The output is written to docs/R_docs/pkgdown/.

Building the Doxygen site for the C++ API

With the stochtree repo checked out and Doxygen installed (brew install doxygen on macOS), run:

sed -i '' 's|^OUTPUT_DIRECTORY *=.*|OUTPUT_DIRECTORY = ../docs/cpp_docs/|' stochtree_repo/Doxyfile
sed -i '' 's|^GENERATE_XML *=.*|GENERATE_XML = NO|' stochtree_repo/Doxyfile
sed -i '' 's|^GENERATE_HTML *=.*|GENERATE_HTML = YES|' stochtree_repo/Doxyfile
mkdir -p docs/cpp_docs/
cd stochtree_repo
doxygen Doxyfile
cd ..

The output is written to docs/cpp_docs/doxygen/.

Building the vignettes with quarto

The vignettes live in the vignettes/ directory and are configured as a standalone Quarto website via vignettes/_quarto.yml. Each .qmd file uses {.panel-tabset group="language"} tabsets to present R and Python code side-by-side. Python cells are executed via reticulate; set the RETICULATE_PYTHON environment variable to point at your .venv interpreter if it isn't picked up automatically.

To render all vignettes at once:

cd vignettes
quarto render

To render a single vignette:

cd vignettes
quarto render bart.qmd

To preview the vignette site locally with live reload:

cd vignettes
quarto preview

The rendered site is written to vignettes/_site/. Individual vignettes use freeze: auto in their frontmatter, so re-renders only re-execute cells whose source has changed. To force a full re-execution, delete vignettes/_freeze/ before rendering.

Regenerating the Python API reference pages

The python-api/reference/*.qmd files are generated by quartodoc from the stochtree package's docstrings. They are checked into the repo, so a normal quarto render will render whatever is already there. If you've updated docstrings in the stochtree Python package, regenerate them first:

source .venv/bin/activate
quartodoc build

This reads the quartodoc: block in _quarto.yml and writes updated .qmd files to python-api/reference/. Run it from the repo root. After regenerating, commit the updated .qmd files and run quarto render as normal.

The CI workflow always runs quartodoc build before quarto render so the live site stays in sync with the latest package docstrings.

Building the overall website

The full site (vignettes + Python API reference + embedded pkgdown/Doxygen) is built from the repo root with:

quarto render

This requires pkgdown and Doxygen output to already exist at docs/R_docs/pkgdown/ and docs/cpp_docs/doxygen/ respectively (the CI workflow builds these before running quarto render). For iterating on vignettes alone, the cd vignettes && quarto render workflow described above is faster.

Freeze cache note: The vignette .qmd files use freeze: auto, so re-renders only re-execute cells whose source has changed. The freeze cache lives at _freeze/vignettes/ (top-level render) or vignettes/_freeze/ (standalone vignette render). If you switch between the two render modes, copy the cache to the appropriate location before rendering to avoid unnecessary re-execution.

The CI workflow (.github/workflows/docs.yml) handles the full build and deploys the output _site/ directory to the gh-pages branch.