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.
-
src
: directory of source files for Stan and CmdStan guides and reference manuals, each in its own named subdirectory:src/cmdstan-guide
- CmdStan Guidesrc/functions-reference
- Stan Functions Referencesrc/reference-manual
- Stan Reference Manualsrc/stan-users-guide
- Stan Users Guide
-
docs
: the directorydocs
on branchmaster
is the publishing source for the project pages site. Whenever a verified member of the Stan organization pushes todocs
on branchmaster
, GitHub (re)builds and (re)deploys the website.
The documentation source files are written in Rmarkdown and the RStudio's bookdown package converts these to HTML and pdf. Required bookdown version: 2.23 or higher, cf the bookdown changelog. Reported via issue #380.
The conversion engine is Pandoc. It is bundled with RStudio. To use the build scripts to build the docset, you might need to install Pandoc separately.
To build the pdf version of the docs, you will need to install LaTeX as well. The Stan documentation uses the Lucida fonts, which must be installed manually.
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.
Requires Python 3.7 or higher, due to call to subprocess.run
, kwarg capture_output
.
- 2 required argments: Stan version, expecting 2 positive integer arguments, e.g.
2 28
- 2 optional arguments: . The document name corresponds to the name of the
src
subdirectory orall
. The output format is eitherhtml
orpdf
.
Build script examples
python build.py 2 28
- creates directorydocs/2_28
as needed; populates it will all generated documentation.python build.py 2 28 functions-reference
- builds both HTML and pdf versions of the Stan functions reference, resulting documents are underdocs/2_28
python build.py 2 28 functions-reference pdf
- builds only the pdf version of the Stan functions reference, resulting document isdocs/2_28/functions-reference_2_28.pdf
python build.py 2 28 all pdf
- builds all pdfs from the Stan documentation set, resulting pdfs are indocs/2_28
.
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.
To build a single documet, you must have R or RStudio installed.
To build a document from the command line, first cd
to the correct src
dir,
then use the Rscript
utility.
# build html
> Rscript -e "bookdown::render_book('index.Rmd', output_format='bookdown::gitbook')"
# build pdf
> Rscript -e "bookdown::render_book('index.Rmd', output_format='bookdown::pdf_book')"
The output will be written to subdirectory _build
.
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.