documentation: Provide info how to set up pedantic mode of compilation

[jerzybaranowski]

Summary:

After long reading and going through code I still can't turn on the pedantic mode from cmdstanpy.
I think that it should be given as an example.
Search through documentation for 'pedantic' leads you to source for cmdstanpy.compiler_opts

[WardBrian]

Pedantic mode is an option for the stanc3 compiler, so you can enable it in the constructor like:

 cmdstanpy.CmdStanModel(stan_file="./bernoulli.stan", stanc_options={"warn-pedantic":True})

or in calls to compile in the same way.

An example of this would be useful, but I generally don't think using pedantic mode is very informative. Judging whether the warnings it raises are legitimate or not can be as difficult as manually diagnose issues in the model.

[jerzybaranowski]

Well, I thought to do it this way, but unfortunately it does not work. No warnings, no anything. And I don't believe my code to be warning free.

[WardBrian]

I just manually edited the included bernoulli example to have a second prior on theta and ran the following, with output:

In [2]: m = cmdstanpy.CmdStanModel(stan_file="./bernoulli.stan", stanc_options={"warn-pedantic":True})
12:21:07 - cmdstanpy - INFO - compiling stan file /home/brian/Dev/cpp/cmdstan/examples/bernoulli/bernoulli.stan to exe file /home/brian/Dev/cpp/cmdstan/examples/bernoulli/bernoulli
12:21:16 - cmdstanpy - INFO - compiled model executable: /home/brian/Dev/cpp/cmdstan/examples/bernoulli/bernoulli
12:21:16 - cmdstanpy - WARNING - Stan compiler has produced 2 warnings:
12:21:16 - cmdstanpy - WARNING - 
--- Translating Stan model to C++ code ---
bin/stanc --warn-pedantic --o=/home/brian/Dev/cpp/cmdstan/examples/bernoulli/bernoulli.hpp /home/brian/Dev/cpp/cmdstan/examples/bernoulli/bernoulli.stan
Warning in '/home/brian/Dev/cpp/cmdstan/examples/bernoulli/bernoulli.stan', line 10, column 2: The
    parameter theta is on the left-hand side of more than one tilde
    statement.
Warning: The parameter theta has 2 priors.

--- Compiling, linking C++ code ---
...

So it does output warnings if they exist. You can also try https://rok-cesnovar.github.io/stanc3js-demo/pedantic.html to run pedantic mode on your code separately to see if any warnings are produced

[jerzybaranowski]

Ok, so either pedantic is absolutely useless, or I'm an amazing stan programmer ;p

[jerzybaranowski]

Also if we are talking about documenting compiler options: Why auto-format and multiple others are ignored?

[mitzimorris]

• many of the compiler options are only useful to the Stanc compiler developers.
• when new compiler options are added to the language, this info doesn't make it into the docs for all the interfaces. poor coordination and communication.

[WardBrian]

Auto formatting in particular is not useful as a part of compilation, because you want the output of that separately. This is why model.format() triggers this, same for the methods on info