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).
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.
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.
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.
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.
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.
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.:
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.
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.
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.
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?
