Repository docs

Repository for the sources and published documentation set, versioned for each Stan minor release.

• The Stan User's Guide - example models and techniques for coding statistical models in Stan and using them to do inference and prediction.
• The Stan Reference Manual - specification for Stan language and core inference algorithms.
• The Stan Functions Reference - functions and distributions built into the Stan language.
• The CmdStan Guide - guide to the reference command-line interface.

Repository directory structure

• src : directory of source files for Stan and CmdStan guides and reference manuals, each in its own named subdirectory:

  • src/cmdstan-guide - CmdStan Guide
  • src/functions-reference - Stan Functions Reference
  • src/reference-manual - Stan Reference Manual
  • src/stan-users-guide - Stan Users Guide

• docs: the directory docs on branch master is the publishing source for the project pages site. Whenever a verified member of the Stan organization pushes to docs on branch master, GitHub (re)builds and (re)deploys the website.

Documentation toolset

We use Quarto to build the HTML website and standalone pdfs; previously, we used bookdown. Download quarto To build the pdf version of the docs, you will need to install LaTeX as well.

Quarto accepts .qmd source files and uses the Pandoc conversion engine.

Both the Stan website (repository: stan-dev.github.io) and the docs use the same quarto theming from the repository quarto-config.

Scripts to build and maintain the docset

Check out submodule quarto-config into the src subdirectory

To build the docs locally, you must first clone the quarto-config repo into the src subdirectory.

cd src
git clone https://github.com/stan-dev/quarto-config

build.py

The program build.py convert the markdown files under src to html and pdf and populates the docs dir with the generated documentation. This script should be run from the top-level directory of this repository.

Requires Python 3.7 or higher, due to call to subprocess.run, kwarg capture_output.

• 2 required arguments: Stan version, expecting 2 positive integer arguments, e.g. 2 28
• 2 optional arguments: . The output format is either website or pdf. The document name corresponds to the name of the src subdirectory or all.

Build script examples

pwd  # check that you're in the top-level directory of this repository, path should end in  "/stan-dev/docs"
python build.py 2 35  # creates directory docs/2_35 as needed; populates it will all generated documentation
python build.py 2 35 website  # builds the docs website in docs/2_35
python build.py 2 35 pdf functions-reference  # builds only the pdf version of the Stan functions reference,  resulting document is docs/2_35/functions-reference-2_35.pdf
python build.py 2 35 pdf all # builds all pdfs from the Stan documentation set, resulting pdfs are in docs/2_35

Additional scripts

The release process generates a new documentation set and adds links and redirects across the docset.

• add_redirects.py manages the redirects from unversioned links to the latest version.
• link_to_latest.py adds the "latest version" link into a docset.

The Stan Functions Reference contains HTML comments which describe the function signature for all functions. The script extract_function_sigs.py is used to scrape these signatures into a plain text file.

GitHub Pages

This repository uses GitHub Pages to serve the project pages site with URL https://mc-stan.org/docs. The publishing strategy is to serve the contents of the directory docs on branch master. The docs directory contains an empty file named .nojekyll so that GitHub will treat the contents as pre-generated HTML instead of trying to run jekyll.