add CmdStan manual

[mitzimorris]

Summary:

Convert CmdStan docs to Rmarkdown and publish as part of docs.

Description:

Companion issue to stan-dev/cmdstan#657

Additional Information:

Update docs per all issues filed on CmdStan repo:

• https://github.com/stan-dev/cmdstan/issues/715
• https://github.com/stan-dev/cmdstan/issues/624
• https://github.com/stan-dev/cmdstan/issues/550

Current Version:

v2.18.0

[rok-cesnovar]

Despite what I said earlier, I think it would be best to just open the PR and merge it to build with Jenkins and then fix if there is anything to fix.

Sorry for flip-flopping on this.

[mitzimorris]

merge it to build
what does this mean?

with GitHub pages hosting, it won't be published unless we add all the generated html and pdfs to the docs/docs dir.

[mitzimorris]

are you suggesting we push and merge current version to master and publish 2_23 docs, allowing users to file issues instead of commenting on the PR? this totally works for me.

[rok-cesnovar]

are you suggesting we push and merge current version to master and publish 2_23 docs

Yes. This will be easiest.

Sorry for the confusing wording.

[jgabry]

are you suggesting we push and merge current version to master and publish 2_23 docs, allowing users to file issues instead of commenting on the PR? this totally works for me.

Sounds good to me too!

[mitzimorris]

https://mc-stan.org/docs/2_23/cmdstan-guide/

[rok-cesnovar]

This looks really nice. Everything worked and formatted as expected, I found no broken links.

I have a few suggestions unrelated to the switch to the .Rmd format. If you want we can also fix any of them separately:

• in https://mc-stan.org/docs/2_23/cmdstan-guide/cmdstan-installation.html just list the minimum compilers:
  • Linux and macOS: g++ 4.9.3 or clang 6.0
  • Windows: g++ 4.9.3 (available with RTools 3.5)

On Windows we strongly recommend using g++ 8.1 which is available as part of RTools 4.0. On macOS we recommend the use of the clang compiler available with XCode (is this correct? I have no idea about macs).

• in 1.3 I would change the cloning instructions to:

> git clone https://github.com/stan-dev/cmdstan.git --recursive
> cd cmdstan
> make build

• in 3.1 I think there is a "the" missing in "In the call to Make, the target is name of the CmdStan"

• I am not sure of the intention of 3.3. I dont see any added value in what is written there. We should either show an example of what happens if we introduce an error in the Bernoulli model, or just remove this.

• in 3.4 the final two sentences are: "This is what a compiler error looks like. This is what other kinds of errors look like." I would change the last sentence to something like: "If this happens, please report the error on the Cmdstan Github repository, together with the Stan program and the error thrown when compiling."

• in 4.1 the example calls should not have JSON in caps

• 4.4 should mention the possibility of showing other percentiles and link to 15

• example for section 12 (though this is probably a separate issue). At least some more details are needed in my opinion.

• in 14 change allow_undefined and include_paths to allow-undefined and include-paths (that would close https://github.com/stan-dev/cmdstan/issues/897) and mention that the underscored versions are deprecated. Also 14 should mention warn-pedantic (but maybe wait for Add pedantic mode doc to reference manual #201).

[jgabry]

@mitzimorris This looks awesome, thank you!! And good suggestions @rok-cesnovar.

I think we should should mention CmdStanR and CmdStanPy somewhere. For example in the Introduction it says:

CmdStan provides the programs and tools to compile Stan programs into C++ executables that can be run directly from the command line, together with a few utilities to check and summarize the resulting outputs. CmdStan is one of several interfaces to Stan; there are also R, Python, Matlab, Julia, and Stata interfaces.

We could maybe add a sentence like:

CmdStan itself is intended to be run from the command line, however it is also possible to use the packages CmdStanR and CmdStanPy, which provide interfaces to CmdStan from R and Python.

[mitzimorris]

I am not sure of the intention of 3.3. I dont see any added value in what is written there. We should either show an example of what happens if we introduce an error in the Bernoulli model, or just remove this.

you are correct - the last two sentences are notes to self. will correct

[mitzimorris]

4.4 should mention the possibility of showing other percentiles and link to 15

noted - this will be done for 2.24 release - inasmuch as we're publishing to 2.23, omitting.

[mitzimorris]

example for section 12 (though this is probably a separate issue). At least some more details are needed in my opinion.

noted - as does the quickstart guide chapter on generated quantities.

[mitzimorris]

@rok-cesnovar - many thanks for the careful read-through. made the easy suggested changes.

[mitzimorris]

CmdStan itself is intended to be run from the command line, however it is also possible to use the packages CmdStanR and CmdStanPy, which provide interfaces to CmdStan from R and Python.

good suggestion. also mention that we are happy to solicit wrapper implementations in other languages.

[mitzimorris]

all suggestions implemented.