Move user's guide to new repo?

Developers
1

I propose we

  1. start a new public stan-dev repo and move the existing user’s guide there and give it the working title, Bayesian Statistics using Stan (this is what @andrewgelman has been calling “the Stan Book”) and base it on the latest released RStan (though the book doesn’t actually go into the R code—it’s system neutral), and

  2. keep the reference manual and functions reference in the existing stan-dev/stan repo and keep them up to date with the develop branch on stan-dev/stan, using simple bookdown rather than requiring RStan.

The basis for the new repo will be stan-dev/stan branch feature/2563-users-guide-html, on which

  • I converted the user’s guide to bookdown so we could generate html and pdf, and
  • Andrew added 100 pages of introductory examples and workflow using RStan.

Keeping the reference manual and functions reference simple should allow them to be built using CircleCI or even simplified back to not need CircleCI.

We can publish versions of the book periodically with CRC and send the royalties to NumFOCUS if people are interested. The authorship is “Stan Development Team”, so it’s meant to be part of the project, not just me and Andrew!

5 Likes
2

more context: this is what’s causing failure for https://github.com/stan-dev/stan/pull/2640 which try to do a make docs from within a docker container. the docker image has to have rstan and rstanarm installed, but the installed packages aren’t using same version of stan as is being tested.

in order to get the new user’s guide on branch https://github.com/stan-dev/stan/tree/feature/2563-users-guide-html to build locally on my Mac, which has tex and pandocs installed, I needed to install the latest version of R, then from within R I installed the following packages:

install.packages("rstan", repos = "https://cloud.r-project.org/", dependencies=TRUE)
install.packages("bookdown")
install.packages("arm")
install.packages("rstanarm")
install.packages("lubridate")
install.packages("tufte")

after this, I was able to build the user’s guide via the script https://github.com/stan-dev/stan/blob/feature/2563-users-guide-html/src/docs/users-guide/_build.sh

this took a real long time…

1 Like
3

Thanks, Bob and Mitzi!

4

As in over 30 minutes. It has to compile and run all those models. I turned caching back on, since that wasn’t the problem, so subsequent builds will be faster. The problems are:

  • Stan programs take forever to compile
  • some Stan programs take a very long time to run
  • the markdown toolchain is slow
  • that script builds both the html and the pdf versions

I checked that the pdf versions build in pdflatex with the built-in charter font. That looks closest to my preferred Lucida fonts, which I have configured to be used optionally if they’re available, like for our manuals.

Charter sets up a better version of Courier than Times or Computer Modern. But that’s still nowhere near as nice as the Lucid combination of:

  • roman: Lucida Bright
  • typewriter: Lucida Console
  • math: Lucida Bright Math (I think—it may be called something else, but it matches the other fonts)

But I hate that Lucida Console is proprietary. Maybe a different version of TeX/LaTeX than pdflatex would be better for font choices. I’ve never tried one.

5

I think it’s a good idea to move to Jenkins docker builds in pipeline anyway, so the circleCI thing shouldn’t be a limitation. That said, I’m not sure if there are action items for me here. Mitzi, if you push your local dockerfile changes to the branch, Jenkins should automatically build a new docker image from them and use that. Let me know if I can help in other ways.

Docker tip: When adding stuff to existing Dockerfiles, adding the new instructions or packages to the end allows the beginning of the file to be used from cache.