Building and maintaining the documentation

Render or preview saved results

Install the Quarto CLI for your platform. On macOS, brew install --cask quarto is also available. Check quarto --version; this project was rendered with Quarto 1.10.18.

From the repository root:

quarto render docs
quarto preview docs

The website reuses saved computations in docs/_freeze/. Keep this directory in version control: a complete website render does not require Python, R, or a built PHP extension when those saved results are present. The JSON comparison report, reference fixtures and executable source code are also retained in the repository. Generated HTML/assets are checked in for GitHub Pages; .qmd files remain the editable sources. Quarto’s local .quarto/ state stays gitignored.

A render that reuses saved outputs is a presentation check, not a fresh numerical verification. The walkthroughs show versions from their last execution. Quarto’s freeze documentation explains why incremental file renders execute code even when a project-wide render reuses outputs.

Recompute the walkthroughs

Follow development setup to select matching PHP and headers, and install R with Rscript available. The mixed-model reference also requires R’s lme4 package, plus nlme for the published-data comparison. These are development dependencies rather than PHP runtime dependencies:

Rscript -e 'install.packages(c("lme4", "nlme"), repos="https://cloud.r-project.org")'

From the repository root:

python3 -m venv .context/notebooks-venv
.context/notebooks-venv/bin/pip install -r docs/notebooks/requirements.txt
export QUARTO_PYTHON="$PWD/.context/notebooks-venv/bin/python"
# macOS development installation; select matching paths on your platform.
export PHP=/opt/homebrew/bin/php
export PHP_CONFIG=/opt/homebrew/bin/php-config
cargo build -p phit --locked
export STATS_EXTENSION="$PWD/target/debug/libphit.dylib"
# Linux: use libphit.so and matching PHP/PHP_CONFIG paths.
.context/notebooks-venv/bin/python docs/verifications/compare_ols.py
quarto render docs/notebooks/ols-math.qmd
quarto render docs/notebooks/ols-verification.qmd
quarto render docs/notebooks/lmm-math.qmd
quarto render docs/notebooks/lmm-verification.qmd
quarto render docs/notebooks/lmm-public-verification.qmd
quarto render docs/data/lmm/index.qmd
quarto render docs/benchmarks/lmm.qmd
quarto render docs

The individual page renders execute their code and refresh the saved outputs; the final full render assembles the website. RSCRIPT can select a non-default Rscript executable. QUARTO_PYTHON selects the virtual environment without adding machine-specific paths to the project configuration. Review changes to .qmd, _freeze/ and verifications/ols-results.json together. Input-data or estimator changes require re-execution even if the prose has not changed.

Recompute each model’s notebooks

With the environment above, each estimator’s comparison script and notebooks run in this order:

export QUARTO_PYTHON="$PWD/.context/notebooks-venv/bin/python"
.context/notebooks-venv/bin/python docs/verifications/compare_ols.py
quarto render docs/notebooks/ols-math.qmd
quarto render docs/notebooks/ols-verification.qmd
.context/notebooks-venv/bin/python docs/verifications/compare_logistic.py
quarto render docs/notebooks/logistic-math.qmd
quarto render docs/notebooks/logistic-verification.qmd
.context/notebooks-venv/bin/python docs/verifications/compare_probit.py
.context/notebooks-venv/bin/python docs/verifications/compare_poisson.py
quarto render docs/notebooks/probit-math.qmd
quarto render docs/notebooks/probit-verification.qmd
quarto render docs/notebooks/poisson-math.qmd
quarto render docs/notebooks/poisson-verification.qmd
.context/notebooks-venv/bin/python docs/verifications/compare_lmm.py
quarto render docs/notebooks/lmm-math.qmd
quarto render docs/notebooks/lmm-verification.qmd
quarto render docs

The individual page renders execute all chunks in order and update _freeze/. Review source, output and comparison-report diffs when regenerating. Outputs record evidence from the environment used, not a guarantee for every platform. The verification scripts capture PHP warnings to keep JSON output valid, then show and check those warnings explicitly. Use a Quarto-compatible editor for interactive .qmd authoring; generated .ipynb files are not the maintained source.

Writing a walkthrough

Each implemented estimator has an executable walkthrough. Do not create placeholder notebooks for methods phit does not implement.

Use a small reproducible simulated dataset with named variables, units, noise, and meaningful relationships. State its generating equation, seed, population parameters, and observed sample correlations. Save and share the actual observations; label them synthetic and explain that correlation alone is not causation. See the learning-data convention. State the model assumptions and input ordering, derive the calculations before displaying them, connect fields to production code, and explain edge cases. Supply equivalent R, statsmodels and PHP calls when those references support the estimator. State any differences in statistical conventions rather than silently adapting one library’s results. Keep assertions near the results and preserve executed outputs. Share inputs with reference tests where possible; avoid three separate datasets that only look similar.

Authoring and verification

Edit .qmd files directly. Ordinary fenced blocks such as python, r and php are displayed examples; {python} chunks execute in the Jupyter kernel. Both OLS walkthroughs use Python chunks, with the comparison runner invoking R and PHP. Execution starts in docs/ and the code discovers the repository root by locating Cargo.toml. A missing dependency or failed assertion must fail the render.

Use relative links to .qmd pages so Quarto rewrites them to HTML links. Keep local reference data and scripts alongside the verification document. Each future implemented estimator should have a derivation walkthrough and equivalent-model verification evidence, following the notebook guide.

For prose-only pages, render the site and check navigation and local links. Any edit to a computational walkthrough (including prose) requires an individual page render to update its frozen content. For computational edits, rerun the affected pages and comparison scripts, inspect output, and run the appropriate Rust/PHP checks. Saved results must never be mistaken for a new estimator test run.

Standard figures

All benchmark and notebook figures use the shared R/ggplot2 strategy in Figure conventions. SVG/PNG exports, fixed language ordering, colors/shapes, units, scale choices and input/package provenance use the same renderer. Python remains a numerical/verification notebook engine rather than a second drawing implementation. Matplotlib is not a documentation dependency.

To refresh saved figures without estimating or timing anything:

Rscript docs/figures/render.R --all
./scripts/render-docs

The renderer uses saved reports and small notebook-exported point snapshots. Individual .qmd execution invokes the R renderer when appropriate. Saved images and frozen outputs support browsing/rendering without rerunning scientific checks.

Publish

phpstats.org imports the rendered HTML committed under docs/, and GitHub Pages serves the same directory at https://phpstats.github.io/phit/. Neither runs Quarto. The site’s navigation is the sidebar in docs/_quarto.yml, so every page listed there needs its rendered HTML committed. After editing .qmd sources or refreshing frozen results, run:

./scripts/render-docs

Commit the regenerated HTML/assets with their sources and push to main. docs/.nojekyll lets GitHub Pages serve the static Quarto website directly, including asset directories containing underscores. quarto render docs alone writes only docs/_site/; the script also copies the result into docs/.