Prettify Website / Require_* doxygen / moving the wiki

[SteveBronder]

Summary

I really don't like the wiki. I find it hard to remember where is what and things are not terribly well sorted. While I was building the doxygen module for the new require_* type traits I figured we have a math site so why not structure it a bit and put stuff over there.

You can run make doxygen to see the new site (You'll need the graphvis package installed for making the call graphs).

There's now a tab on the LHS that groups a few of the wiki pages together. Under the modules tab you'll see functions and classes grouped together.

The goal here is that 'experimental' features or docs we are still working on are in the wiki then once everything is fleshed out and official we move it over to the website.

This also includes instructions inside of the doxygen folder for how to add new .md files to the table of contents.

Checklist

• Math issue Add doxygen module for #1392's require_* template metaprogramming #1396

• Copyright holder: Steve Bronder

  The copyright holder is typically you or your assignee, such as a university or company. By submitting this pull request, the copyright holder is agreeing to the license the submitted work under the following licenses:
  - Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
  - Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

• the basic tests are passing

  • unit tests pass (to run, use: ./runTests.py test/unit)
  • header checks pass, (make test-headers)
  • docs build, (make doxygen)
  • code passes the built in C++ standards checks (make cpplint)

• the code is written in idiomatic C++ and changes are documented in the doxygen

• the new changes are tested

[SteveBronder]

@seantalts can we install graphvis on wherever Jenkins is? Would be nice to have the call and callee graphs

[seantalts]

Sure! What's the exact steps you need me or Nic to do?

[SteveBronder]

Is the OS linux or mac?

For mac

brew install graphviz

linux

apt install graphviz

[seantalts]

Hmm, can you find a docker image that has that plus whatever other stuff you need and use that? Jenkins makes that pretty easy especially if the docker image exists already. Is this part of doxygen?

[seantalts]

Happy to install it on the hardware machines we have and then we could restrict the build to those machines as well, but the docker thing would let it run in more places.

[SteveBronder]

This docker file seems to have the right stuff (I think?)

https://github.com/BrainTwister/docker-devel-env/tree/master/doxygen-1.8.14

Do we have a repo of dockerfiles available somewhere?

[SteveBronder]

Cuz I can probably just slap that stuff on top of our current dockerfile

[SteveBronder]

@wds15 if you get some time next week can you check out the .md files for threading I grabbed from the wiki? Just to make sure they are both up to date and are titled right. If you want to make any changes feel free to push directly to the branch

https://github.com/stan-dev/math/pull/1397/files?file-filters%5B%5D=.md#diff-d6281a65fbec195375fbb1a0544e74b1

https://github.com/stan-dev/math/pull/1397/files?file-filters%5B%5D=.md#diff-d251a2d144d438d362397278cdb2aa7c

[stan-buildbot]

(stat_comp_benchmarks/benchmarks/gp_pois_regr/gp_pois_regr.stan, 0.99)
(stat_comp_benchmarks/benchmarks/low_dim_corr_gauss/low_dim_corr_gauss.stan, 1.03)
(stat_comp_benchmarks/benchmarks/irt_2pl/irt_2pl.stan, 1.0)
(stat_comp_benchmarks/benchmarks/pkpd/one_comp_mm_elim_abs.stan, 1.0)
(stat_comp_benchmarks/benchmarks/eight_schools/eight_schools.stan, 1.01)
(stat_comp_benchmarks/benchmarks/gp_regr/gp_regr.stan, 1.01)
(stat_comp_benchmarks/benchmarks/arK/arK.stan, 1.0)
(performance.compilation, 0.99)
(stat_comp_benchmarks/benchmarks/low_dim_gauss_mix_collapse/low_dim_gauss_mix_collapse.stan, 1.0)
(stat_comp_benchmarks/benchmarks/low_dim_gauss_mix/low_dim_gauss_mix.stan, 1.0)
(stat_comp_benchmarks/benchmarks/sir/sir.stan, 0.98)
(stat_comp_benchmarks/benchmarks/pkpd/sim_one_comp_mm_elim_abs.stan, 0.97)
(stat_comp_benchmarks/benchmarks/garch/garch.stan, 0.99)
(stat_comp_benchmarks/benchmarks/gp_regr/gen_gp_data.stan, 0.98)
(stat_comp_benchmarks/benchmarks/arma/arma.stan, 1.0)
Result: 0.99696929900
Commit hash: e914245

[SteveBronder]

@syclik @bob-carpenter not sure who to tag on review for this. You can run make doxygen to see the site locally.

@charlesm93 This might also be a nice place to have docs for the ODE solvers. You can add a \defgroup like I have here for the probability distributions then tag the solvers docs with \ingroup your_ode_solver_tag

https://github.com/stan-dev/math/pull/1397/files#diff-86921eaf1325ba012f545f449fc93cfcR4

@rok-cesnovar if you have anytime next week can you add some stuff for the section on OpenCL? You can just either push directly or make a branch no worries either way.

You can add the text directly where we make the opencl /defgroup

https://github.com/stan-dev/math/pull/1397/files#diff-7be8a76b90a41c3a23528e2b98e3a2a0R6

[SteveBronder]

I hope people don't mind but I wanted to show everyone the new site so I slammed up it up live. I think it looks pretty nice!

http://mc-stan.org/math/

[stan-buildbot]

(stat_comp_benchmarks/benchmarks/gp_pois_regr/gp_pois_regr.stan, 1.02)
(stat_comp_benchmarks/benchmarks/low_dim_corr_gauss/low_dim_corr_gauss.stan, 1.0)
(stat_comp_benchmarks/benchmarks/irt_2pl/irt_2pl.stan, 1.0)
(stat_comp_benchmarks/benchmarks/pkpd/one_comp_mm_elim_abs.stan, 1.0)
(stat_comp_benchmarks/benchmarks/eight_schools/eight_schools.stan, 0.99)
(stat_comp_benchmarks/benchmarks/gp_regr/gp_regr.stan, 1.01)
(stat_comp_benchmarks/benchmarks/arK/arK.stan, 1.01)
(performance.compilation, 1.02)
(stat_comp_benchmarks/benchmarks/low_dim_gauss_mix_collapse/low_dim_gauss_mix_collapse.stan, 1.0)
(stat_comp_benchmarks/benchmarks/low_dim_gauss_mix/low_dim_gauss_mix.stan, 1.0)
(stat_comp_benchmarks/benchmarks/sir/sir.stan, 1.01)
(stat_comp_benchmarks/benchmarks/pkpd/sim_one_comp_mm_elim_abs.stan, 0.99)
(stat_comp_benchmarks/benchmarks/garch/garch.stan, 0.99)
(stat_comp_benchmarks/benchmarks/gp_regr/gen_gp_data.stan, 0.98)
(stat_comp_benchmarks/benchmarks/arma/arma.stan, 1.0)
Result: 1.00035764881
Commit hash: 0fe5967

[SteveBronder]

Nice! Does anyone want to look this over / approve? I think mostly the thing to look at is the Jenkinsfile changes

[seantalts]

Am I doing something wrong? The only Jenkinsfile change I see is that it now updates the Math library documentation whenever we merge to develop?

[SteveBronder]

Oh lol forgot I removed stuff any changes to the jenkins stuff

What do you think is the best way to review this? essentially it just has a bunch of docs and stuff and makes some groups for doxygen modules

[SteveBronder]

@seantalts after I fix this conflict can we merge this? I have to keep updating it otherwise

[SteveBronder]

@rok-cesnovar @bob-carpenter can we merge this once it passes? It touches a good number of comments so I have to keep dealing with little merge conflicts

Site looks nice tho'!

http://mc-stan.org/math/

[seantalts]

Hey yeah sorry, I meant to reply - I think @bob-carpenter or @syclik are the resident doxygen experts. It all looks good to me but I honestly don't know what our policies on doc are at this level.

[edit] To make it easier for you guys, if you don't have a problem with adding .md files to the doxygen folder for all the wiki style doc we had before and you don't mind adding \ingroup tags to a bunch of doxygen strings I think it should be good to go and a vast improvement. I'm pretty excited about pulling this doc that used to live on the wiki into git so it is versioned :)

[syclik]

Just took a peek. It looks good. I'll second @seantalts's comment (in his edit): moving doc to GitHub would be great! I know the wiki is supposed to be a git repository, but the interface there is different from the code and not chasing doc in two different places is a good thing.

@SteveBronder, one major comment: the build instructions in the README.md are incorrect. (see https://github.com/stan-dev/math#installation) It's missing a critical part indicating that the TBB must be built, not just have the sources available. It doesn't look like this is something you did. Let me know if you want me to split it out into a different issue or if you wanted to tackle it since you've got all the doc changes happening at once.

[SteveBronder]

@SteveBronder, one major comment: the build instructions in the README.md are incorrect. (see https://github.com/stan-dev/math#installation) It's missing a critical part indicating that the TBB must be built, not just have the sources available. It doesn't look like this is something you did. Let me know if you want me to split it out into a different issue or if you wanted to tackle it since you've got all the doc changes happening at once.

We could solve it here but that's not really something I know about. It may be easier to have @wds15 do that in a separate PR

[rok-cesnovar]

Looks great to me!

[stan-buildbot]

(stat_comp_benchmarks/benchmarks/gp_pois_regr/gp_pois_regr.stan, 1.0)
(stat_comp_benchmarks/benchmarks/low_dim_corr_gauss/low_dim_corr_gauss.stan, 1.01)
(stat_comp_benchmarks/benchmarks/irt_2pl/irt_2pl.stan, 0.99)
(stat_comp_benchmarks/benchmarks/pkpd/one_comp_mm_elim_abs.stan, 1.03)
(stat_comp_benchmarks/benchmarks/eight_schools/eight_schools.stan, 0.99)
(stat_comp_benchmarks/benchmarks/gp_regr/gp_regr.stan, 1.01)
(stat_comp_benchmarks/benchmarks/arK/arK.stan, 1.0)
(performance.compilation, 1.01)
(stat_comp_benchmarks/benchmarks/low_dim_gauss_mix_collapse/low_dim_gauss_mix_collapse.stan, 1.0)
(stat_comp_benchmarks/benchmarks/low_dim_gauss_mix/low_dim_gauss_mix.stan, 0.99)
(stat_comp_benchmarks/benchmarks/sir/sir.stan, 1.0)
(stat_comp_benchmarks/benchmarks/pkpd/sim_one_comp_mm_elim_abs.stan, 0.96)
(stat_comp_benchmarks/benchmarks/garch/garch.stan, 1.0)
(stat_comp_benchmarks/benchmarks/gp_regr/gen_gp_data.stan, 0.98)
(stat_comp_benchmarks/benchmarks/arma/arma.stan, 1.0)
Result: 0.99920252694
Commit hash: ddaf09c

[SteveBronder]

Good to go?

[rok-cesnovar]

Lets go!

[SteveBronder]

Much appreciated!

Apologies to the folks that have to do merge conflicts because I touched your comment docs