Repo for Stan documentation - now online!


#1

The Stan documentation consists of:

  • Stan Reference Manual
  • Stan Functions Reference
  • Stan book (formerly known as “Stan Users Manual”)

CmdStan has its own users manual. The cmdstan makefile builds the Stan ref-manual and functions reference and copies them to the cmdstan docs dir as part of its docset.

The Stan documentation set has been converted from latex to Rmarkdown. The toolchain to build the docs requires: latex, pandoc, pandoc-citeproc, and the R bookdown package. The cmdstan documentation is still in latex and needs to be converted to Rmarkdown.

If there were a single repo for just the docs, then we could use github’s project pages to serve the html version of the current docs. We could also distribute pdfs of the documentation set for all previous releases.
https://help.github.com/articles/user-organization-and-project-pages/

We can either move all documentation into the existing stan-book repo or create a new repo stan-docs (or whatever).

what do yinz think?
cheers,
Mitzi


#2

Was there a question buried in the post?

Also, we can serve different project pages at mc-stan.org/<project-name-here>


#3

yes, question: repo “stan-book” doesn’t make a good URL for all the docs,
so it would be better to have a repo names stan-docs or just docs from which to serve the reference manual, functions reference, cmdstan manual (eventually), as well as the Stan book.

mc-stan.org/stan-docs/

would be better. create new repo accordingly?

cheers,
Mitzi


#5

Why not just docs? And instead of a new repo, can you just rename the other one?


#7

turned off github pages because this is premature.
cheers,
Mitzi


#8

What is stan-docs? Is this where we’re going to be hosting the rmarkdown for all the doc:

  • User’s Guide / Stan Book
  • Reference Manual
  • Functions Reference

I think all the doc should be moved to a single repo. I’m OK if we get rid of the stan-book repo and put everything in a repo called docs. I agree that we don’t need stan to modify repo names in the stan-dev organization.


#9

there is now a repo called docs and using GitHub project pages we can host a static website that will have URL mc-stan.org/docs.

The static website will contain:

  • online documentation for the current Stan release
  • pdfs for previous releases

Right now, this repo has a single branch master and is organized into two directories: src and docs. The src dir contains bookdown sources for the manuals. So far I’ve added the Stan reference manual and the functions reference manual.

The repo will be configured so that GitHub will serve the contents of the docs dir. The R bookdown package will be used to build gitbook HTML pages for each manual as well as the pdf version of each manual.

URLs into the docs dir will be:

There current build script _build.sh is only a placholder for a proper build system - possibly using Travis - which will update the docs site for each release.


#10

We should move the Stan book to this repo. Let’s coordinate with @andrewgelman tomorrow to make sure he doesn’t have any branches in progress that might get messed up by the move.

What’s current? The problem we face is that PyStan and RStan are lagging as much as a few months behind CmdStan. Do we just change the basic HTML as soon as CmdStan changes and then assume PyStan and RStan will somehow update their docs to point to older versions?

Previously, you had suggested having the older HMTL versions up with a sym link to the most recent version under the top-level index. I’m not sure even that’ll solve this problem.


#11

I’ve made no changes on the book for a couple months so feel free to move it wherever. I do have some thoughts on where to go next on the book.
A


#12

The docs repo now contains the Stan reference manual, functions reference, and user’s guide (a.k.a. “Bayesian Statistics Using Stan”)

We can move the CmdStan, RStan, and PyStan docs into this repo as well.
The landing page is
http://mc-stan.org/docs/

The HTML versions of the Stan manuals were introduced in 2.18. The index page has links to the pdfs for 2.17. Going forward, there will be new versions of the HTML and pdfs with each release.

Next steps here are:
1. add manuals for the interfaces

this definitely needs to be done for CmdStan because right now there’s not an online version of the manual. the Rmarkdown/pandoc/knitr toolchain is nice because we can generate both online and print versions of the docs.

2. create unversioned HTML docs which automatically redirect to the latest version for which the URL is valid, e.g.:

a request for “http://mc-stan.org/docs/functions-reference/step-functions.html” will automatically redirect to “http://mc-stan.org/docs/2_18/functions-reference/step-functions.html” for now, and next release will redirect to “http://mc-stan.org/docs/2_19/functions-reference/step-functions.html”.
if a page (i.e. chapter) is removed from the next version of the manual, the redirect page won’t be updated, so it will still work. don’t yet have the scripts to make this happen in place.

after some offline discussion with Bob, not sure if this is a real problem that needs to be solved

in the meantime, happy browsing,
Mitzi


Documentation bugs
#13

Our docs are currently in rst format and use sphinx (?) to read part of the documentation from code. Should we do something similar here?

cc. @ariddell


#14

not necessarily. if the Python ecosystem meets your docs needs, that’s fine. I think I’ll amend the above statement about the interfaces. the CmdStan docs need to be pulled into this repo.

we need to do this for the Stan and CmdStan docs because for a long time the docs were only distributed as pdfs and this was suboptimal because users couldn’t get answers to their questions via a web search. so we converted the documentation from latex to Rmarkdown so we can use knitr/pandoc/bookdown and github pages to build and host the docs respectively.

if you have a way of putting your docs online for your users, that’s great. Rmarkdown/pandoc is just one way to go.


#15

First of all, many thanks to all the effort put in the documentation. It’s excellent!

I’m not sure if this is the best thread to put it, but http://mc-stan.org/docs/bayes-stats-stan/index.html doesn’t seem to work with https. If I go to https://mc-stan.org/docs/bayes-stats-stan/index.html with Firefox on ubuntu I get the enclosed screenshot:

Same is true for https://mc-stan.org. I saw https mentioned in Enabling HTTPS for the Stan forums?, but that was just for discourse.

Can/Should that be fixed?


#16

most definitely must be fixed.
looking into it.
thanks,
Mitzi


#17

Can the team please host pre-built PDFs for the docs/book? Pandoc toolchain is really fragile I failed to get it working with strange (to me) messages on both Ubuntu and Mac.


#18

the pdf exists here:

we’ll add a link to the web pages.
cheers,
Mitzi


#19

when the Stan documentation was latex only (2.17 and before), the pdfs were prettier. we lost some of that when moving to the gitbook/pandoc toolchain. therefore the new pdfs aren’t nearly as nice as the old ones.


#20

One of my coworkers pointed out to me the docs are complaining about the connection not being secure. I don’t know how the hosting works for this, but last time I needed a cert I just used https://letsencrypt.org/ .

Either that or maybe just use http? It’s just docs anyway?


#21

yes, certs and DNS config need to be changed - I don’t have access to any of that - maybe @syclik does?