Local / Notebooks / Reports

[CGMossa]

Meta: Usually, an issue is raised when we wish to add a new thing, and then various design decisions are raised and decided upon, and then someone (not necessarily the issue creator) may propose a PR to implement said decisions.

Definitions

Local: Files that pertain to you the contributor / developer only and not anyone else;

• [ ] These files shouldn't even be committed, right? I.e. should this folder be included in the .gitignore file?

Notebooks: Scripts that are used to prototype ideas/functions/workflows etc.

Reports: Mostly writings concerning designs, notes, details, meeting notes, slides/presentations, that pertain to the package and its development. In many FOSS projects they have something called RFCs, that would fit in here.

• local, notebooks, and reports should be added to the .Rbuildignore file.

Usage

The way I name notebooks, is by using 00N_notebook_name.R, as to have the order of which prototypes emerged in the filename itself.

If I'm to dictate my ideal template for a notebook it would look like this:

#' ---
#' title: notebook_name
#' author: your_name
#' output: html_document
#' ---
#'
#'
# Mon May 02 11:48:13 2022 ------------------------------

#+ setup, message=FALSE
devtools::load_all()

Let's discuss, in the mean time I'll work on a PR, and once a discussion is done, I'll propose said PR that deals with this.

[CarlijnB]

Hi Mossa and all,

Personally I'm not yet in the habit of using notebooks - so I don't have anything useful to add, only questions to ask.

[So with notebooks you don't mean Rmarkdown notebooks but something somewhat similar created via roxygen?] Edited to add: never mind, I just found this https://bookdown.org/yihui/rmarkdown-cookbook/spin.html to help me understand. It looked similar to Rmarkdown but I was familiar with blocks like ```{r} some code``` , not #+

When do you stick a developing script in a notebook, vs in the R folder on a separate branch? Are these just alternative workflows to choose from , or does the notebook still have a function when using a separate branch for each bit you're working on?

[CGMossa]

I call these things "notebooks" because the terminology was borrowed from Data Science Project cookiecutter. A cookiecutter is a python "package" that creates packages.

So notebooks are just raw r-scripts. I can turn these raw r-scripts into Markdown, if I want to, using spin. There are a few spin rules that I go by: #' turns into markdown, #+ turns into chunks, and finally you've got regular comments with #.

Another thing, you're not supposed to store scripts in R/-folder. Because once a package is loaded, then everything, and I mean everything in R/ folder is sourced. And it is sourced in a particular order as well. That's why you (mostly) only see files with functions in R/-folder.

A "developing script" start out in a notebook. I would have it in the repository with the package, but since it is ignored in the .Rbuildignore, then these scripts do not get sent when people install your package using e.g. remotes::install_github("ku-awdc/epipkg").