# Repo for Stan documentation - now online!

**URL:** <https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738>\
**Category:** Developers\
**Created:** [November 26, 2018, 4:18pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738 "2018-11-26T16:18:17Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [November 26, 2018, 4:18pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/1 "2018-11-26T16:18:17Z")

</div>

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/](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

---

<div class="post-metadata">

**Author:** ![syclik](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/syclik/32/6_2.png) [@syclik](https://discourse.mc-stan.org/u/syclik)\
**Post date:** [November 28, 2018, 3:35am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/2 "2018-11-28T03:35:27Z")

</div>

> [@mitzimorris](#):
>
> what do yinz think?

Was there a question buried in the post?

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

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [November 28, 2018, 12:17pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/3 "2018-11-28T12:17:05Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![syclik](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/syclik/32/6_2.png) [@syclik](https://discourse.mc-stan.org/u/syclik)\
**Post date:** [November 28, 2018, 11:41pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/5 "2018-11-28T23:41:37Z")

</div>

> [@mitzimorris](#):
>
> `mc-stan.org/stan-docs/`
> 
> would be better. create new repo accordingly?

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

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [November 29, 2018, 1:34am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/7 "2018-11-29T01:34:08Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Bob\_Carpenter](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bob_carpenter/32/9230_2.png) [@Bob\_Carpenter](https://discourse.mc-stan.org/u/Bob_Carpenter)\
**Post date:** [November 29, 2018, 1:36am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/8 "2018-11-29T01:36:57Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [November 29, 2018, 2:40am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/9 "2018-11-29T02:40:49Z")

</div>

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:

- [mc-stan.org/docs/reference-manual/index.html](http://mc-stan.org/docs/reference-manual/index.html) : HTML for current
- [mc-stan.org/docs/stan-reference-manual-](http://mc-stan.org/docs/stan-reference-manual-).pdf - for all previous releases.  
etc.

There current build script [\_build.sh](https://github.com/stan-dev/docs/blob/master/_build.sh) is only a placholder for a proper build system - possibly using Travis - which will update the docs site for each release.

---

<div class="post-metadata">

**Author:** ![Bob\_Carpenter](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bob_carpenter/32/9230_2.png) [@Bob\_Carpenter](https://discourse.mc-stan.org/u/Bob_Carpenter)\
**Post date:** [November 29, 2018, 2:45am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/10 "2018-11-29T02:45:53Z")

</div>

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.

> [@mitzimorris](#):
>
> HTML for current

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.

---

<div class="post-metadata">

**Author:** ![andrewgelman](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/andrewgelman/32/1577_2.png) [@andrewgelman](https://discourse.mc-stan.org/u/andrewgelman)\
**Post date:** [November 29, 2018, 2:47am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/11 "2018-11-29T02:47:23Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [November 30, 2018, 9:12pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/12 "2018-11-30T21:12:20Z")

</div>

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/](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](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](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](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

> **[Stan Reference Manual](https://mc-stan.org/docs/2_18/reference-manual/index.html)**
>
> Stan reference manual specifying the syntax and semantics of the Stan programming language.

> **[Stan Functions Reference](https://mc-stan.org/docs/2_18/functions-reference/index.html)**
>
> Reference for the functions defined in the Stan math library and available in the Stan programming language.

> **[Stan User’s Guide](https://mc-stan.org/docs/2_18/stan-users-guide/index.html)**
>
> Stan user’s guide with examples and programming techniques.

---

<div class="post-metadata">

**Author:** ![ahartikainen](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/ahartikainen/32/321_2.png) [@ahartikainen](https://discourse.mc-stan.org/u/ahartikainen)\
**Post date:** [December 1, 2018, 7:25pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/13 "2018-12-01T19:25:11Z")

</div>

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

> **[reStructuredText](https://en.m.wikipedia.org/wiki/ReStructuredText)**
>
> reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation.
> It is part of the Docutils project of the Python Doc-SIG (Documentation Special Interest Group), aimed at creating a set of tools for Python similar to Javadoc for Java or Plain Old Documentation (pod) for Perl. Docutils can extract comments and information from Python programs, and format them into various forms of program documentation...

cc. @ariddell

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [December 1, 2018, 9:18pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/14 "2018-12-01T21:18:42Z")

</div>

> [@ahartikainen](#):
>
> Should we do something similar here?

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.

---

<div class="post-metadata">

**Author:** ![Uri\_Shimron](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/uri_shimron/32/4399_2.png) [@Uri\_Shimron](https://discourse.mc-stan.org/u/Uri_Shimron)\
**Post date:** [December 5, 2018, 9:33am UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/15 "2018-12-05T09:33:43Z")

</div>

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](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](https://mc-stan.org/docs/bayes-stats-stan/index.html) with Firefox on ubuntu I get the enclosed screenshot:

 ![problem%20with%20bayes-stat-stan%20website](https://canada1.discourse-cdn.com/flex030/uploads/mc_stan/original/2X/d/d828aeffb651889f0d3cd39aeaeae931fb34e130.png)

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

Can/Should that be fixed?

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [December 5, 2018, 12:41pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/16 "2018-12-05T12:41:07Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mkesin](https://avatars.discourse-cdn.com/v4/letter/m/b3f665/32.png) [@mkesin](https://discourse.mc-stan.org/u/mkesin)\
**Post date:** [December 5, 2018, 3:17pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/17 "2018-12-05T15:17:01Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [December 5, 2018, 3:51pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/18 "2018-12-05T15:51:21Z")

</div>

> [@mkesin](#):
>
> Can the team please host pre-built PDFs for the docs/book?

the pdf exists here:  
[https://github.com/stan-dev/docs/blob/master/docs/bayes-stats-stan.pdf](https://github.com/stan-dev/docs/blob/master/docs/bayes-stats-stan.pdf)

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

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [December 5, 2018, 4:05pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/19 "2018-12-05T16:05:54Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![bbbales2](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bbbales2/32/77_2.png) [@bbbales2](https://discourse.mc-stan.org/u/bbbales2)\
**Post date:** [December 7, 2018, 6:08pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/20 "2018-12-07T18:08:43Z")

</div>

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/](https://letsencrypt.org/) .

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

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [December 7, 2018, 11:14pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/21 "2018-12-07T23:14:26Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mitzimorris](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/mitzimorris/32/29_2.png) [@mitzimorris](https://discourse.mc-stan.org/u/mitzimorris)\
**Post date:** [December 19, 2018, 2:38pm UTC](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738/22 "2018-12-19T14:38:10Z")

</div>

> [@Uri\_Shimron](#):
>
> Can/Should that be fixed?

[mc-stan.org](http://mc-stan.org) website is now being served securely - or should be - at least, it is on my machine (and our sys admins say so too!)

let me know if you’re still seeing these errors.

cheers,  
Mitzi

[Next page](https://discourse.mc-stan.org/t/repo-for-stan-documentation-now-online/6738.md?page=2)