clean up branches, docs

bbolker commented 2 years ago

@evanjmitchell and I are having a hard time figuring out the status of current branches and how to build and run a 'vanilla' model, ideally both with a simple calibrate(..., <options>) and forecast(..., <options>) and with a simple "set up my vanilla model" script as the first step in a workflow (i.e. add_compartment, add_flow, etc. [or whatever they're really called]).

Also ideally we would be able to simply look at the Gh-pages/pkgdown site and find this all out for ourselves ...

As part of the "sorting out branches", I would very much like it if we could merge a stable TMB version back into master, both because that's where it belongs and because that would make the "flex_specs" vignette show up on the pkgdown/GH pages front end ...

PS the "flex_specs" vignette is nice, but it only indicates what versions of the specs have been frozen or not - not whether a particular spec has been implemented. In particular, adding something to the docs that points out that you can find out via ...

getOption("MP_flex_spec_version")
## [1] "0.1.2"

stevencarlislewalker commented 2 years ago

Thanks for these thoughts @bbolker

stevencarlislewalker commented 2 years ago

Trying to capture this issue, and our conversation today with this: https://github.com/mac-theobio/McMasterPandemic/milestone/7 and this https://github.com/mac-theobio/McMasterPandemic/milestone/8

stevencarlislewalker commented 2 years ago

README items:

[ ] Spec version explanation and functionality for developers
[ ] Makefile usage -- such as it is
[ ] TODO: ...

stevencarlislewalker commented 2 years ago

There is progress @bbolker. Splitting it up into three pieces: user guidance, branch management, and developer guidance.

User Guidance

having a hard time figuring out the status of current branches and how to build and run a 'vanilla' model, ideally both with a simple calibrate(..., ) and forecast(..., ) and with a simple "set up my vanilla model" script as the first step in a workflow (i.e. add_compartment, add_flow, etc. [or whatever they're really called]).

This guide should help. Apparently @mayaearn has had success building models from it.

Also ideally we would be able to simply look at the Gh-pages/pkgdown site and find this all out for ourselves ...

I'm not sure if this is sufficient, but there is now this section of the README on the master branch.

Branch Management

As part of the "sorting out branches", I would very much like it if we could merge a stable TMB version back into master, both because that's where it belongs and because that would make the "flex_specs" vignette show up on the pkgdown/GH pages front end ...

Merging is not yet done. I would rather not do it until the package checks and roxygen stuff gets cleaner. On the other hand the package checks on master are often (always?) failing anyways right now so maybe we should just merge and get it over with?

Developer Guidance

PS the "flex_specs" vignette is nice, but it only indicates what versions of the specs have been frozen or not - not whether a particular spec has been implemented. In particular, adding something to the docs that points out that you can find out via

This should probably not be a vignette, because it is actually for developers. I started working on a contributing guide as well but it is pretty much a stub at the moment. In any case, this specs/dev-guide stuff is the aspect of this ticket that is in the worst shape and is why I haven't closed it.

stevencarlislewalker commented 2 years ago

It is a little unclear to know when this ticket is finished. There is clearly more to do, but I believe that the pkgdown site now points to the things that an adventurous user would need to get started (and has for a while actually).

A while ago we merged a stable TMB branch back to master, and @papsti is currently using this master branch.

The developer guide is still struggling, but there is only so much time ...

mac-theobio / McMasterPandemic