diff --git a/R/README.md b/R/README.md index 8dda6373778cb27a2f6bc66eaf0adb00021c05a1..50a09f6f5131cd542b7d9bf03ef7bf33b0e83aa3 100644 --- a/R/README.md +++ b/R/README.md @@ -4,4 +4,7 @@ The place to keep functions - see [template info](../template.md). -We recommend using [roxygen](https://roxygen2.r-lib.org/) style [documentation](https://style.tidyverse.org/documentation.html). \ No newline at end of file +We recommend: + + * keeping one function per file for easy re-location when bug fixing + * using [roxygen](https://roxygen2.r-lib.org/) style [documentation](https://style.tidyverse.org/documentation.html). \ No newline at end of file diff --git a/template.md b/template.md index f6322863a97fd6b2c8dd8199846749d1a03bcd13..af20540642e6d843c1117ea08dbb800e8f4c4451 100644 --- a/template.md +++ b/template.md @@ -4,16 +4,22 @@ There are as many templates for (R) repos as there R users... Here's ours. We srtucture the repo as a package. We may never build it but usually we do so that the package functions are available everywhere in it - * things you should touch: - * env.R : where we store all the parameters that might be re-used across our repo. Such as colour defaults, data paths etc - * R/ : where we store functions that get built - * analysis/ : where we store .Rmd files and the .R scripts that call them (usually using a `drake` plan) - * docs/ : where we put output generated by the .R/.Rmd code. This is helpful if you are using [github/lab pages](https://guides.github.com/features/pages/). Unfortunately the University of Southampton gitlab service does not currently support this. - * notData/ : where we do not store data. R packages expect certain kinds of data in their 'data/' folders. Do not put your data in it. In fact we recommend **not** putting your data in your repo at all. Yes, this breaks true reproducability but there are reasons: +Things you should touch: + +| Item | Description | +| --- | --- | +| **env.R** | Where we store all the parameters that might be re-used across our repo. Such as colour defaults, data paths etc. We avoid using a project/repo level .Rprofile because it can lead to [a **lot** of confusion](https://support.rstudio.com/hc/en-us/articles/360047157094-Managing-R-with-Rprofile-Renviron-Rprofile-site-Renviron-site-rsession-conf-and-repos-conf +) | +|**DESCRIPTION** | But only if you use this as a tmeplate for your own repo - it is a special file for packages | +| **R/** | Where we store functions that get built | +| **analysis/** | Where we store .Rmd files and the .R scripts that call them (usually using a `drake` plan) | +| **docs/** | Where we put output generated by the .R/.Rmd code. This is helpful if you are using [github/lab pages](https://guides.github.com/features/pages/). Unfortunately the University of Southampton gitlab service does not currently support this. | +| **notData/** | Where we do not store data. R packages expect certain kinds of data in their 'data/' folders. Do not put your data in it. In fact we recommend **not** putting your data in your repo at all. Yes, this breaks true reproducability but there are reasons: * we often use data that is commerecial or sensitive or personal (under GDPR) - so we cannot risk that leaking out * we often use _very large_ datasets which most git/hub/lab services sensibly reject - * we often pull real time data on the fly from elsewhere so storage makes no sense + * we often pull real time data on the fly from elsewhere so storage makes no sense | + +Things you should not touch: - * things you should not touch: - * man/ : created by building the project/package - * NAMESPACE : - ditto - \ No newline at end of file +| **man/** | Created by building the project/package using roxygen| +| **NAMESPACE** | - ditto - \ No newline at end of file