diff --git a/new_pages/collaboration.qmd b/new_pages/collaboration.qmd index abaaba4..2cbac46 100644 --- a/new_pages/collaboration.qmd +++ b/new_pages/collaboration.qmd @@ -71,18 +71,18 @@ However, it becomes even more powerful when used with a online repository such as Github to support **collaborative projects**. This facilitates: - Collaboration: others can review, comment on, and - accept/decline changes + accept/decline changes. - Sharing your code, data, and outputs, and invite feedback - from the public (or privately, with your team) + from the public (or privately, with your team). and avoids: - "Oops, I forgot to send the last version and now you need to - redo two days worth of work on this new file" + redo two days worth of work on this new file". - Mina, Henry and Oumar all worked at the same time on one script and - need to manually merge their changes + need to manually merge their changes. - Two people try to modify the same file on Dropbox and Sharepoint and this creates a synchronization error. @@ -125,7 +125,7 @@ this chapter. Intermediate (more powerfull, but more complex) options include Source Tree, Gitkracken, Smart Git and others. -Quick explanation on [Git clients](https:/happygitwithr.com/git-client.html#git-client). +Quick explanation on [Git clients](https://happygitwithr.com/git-client). *Note: since interfaces actually all use Git internally, you can try several of them, switch from one to another on a given project, use the console punctually @@ -139,7 +139,7 @@ Console) or the Git Bash terminal. ### Github account {.unnumbered} -Sign-up for a free account at [github.com](github.com). +Sign-up for a free account at [github.com](https://github.com/). You may be offered to set-up two-factor authentication with an app on your phone. Read more in the Github [help @@ -156,7 +156,7 @@ clone a project from Github. As when learning R, there is a bit of vocabulary to remember to understand Git. Here are the [basics to get you going](https://www.freecodecamp.org/news/an-introduction-to-git-for-absolute-beginners-86fa1d32ff71/) -/ [interactive tutorial](learngitbranching.js.org). In the next +/ [interactive tutorial](https://learngitbranching.js.org/). In the next sections, we will show how to use interfaces, but it is good to have the vocabulary and concepts in mind, to build your mental model, and as you'll need them when using interfaces anyway. @@ -257,8 +257,8 @@ Two general approaches to set-up are: - Create a new R Project from an existing or new Github repository - (*preferred for beginners*), or -- Create a Github repository for an existing R project + (*preferred for beginners*), or, +- Create a Github repository for an existing R project. ### Start-up files {.unnumbered} @@ -326,13 +326,13 @@ Rstudio and Github desktop. #### In Rstudio {.unnumbered} In RStudio, start a new R project by clicking *File \> New Project \> -Version Control \> Git* +Version Control \> Git*. - When prompted for the "Repository URL", paste the HTTPS URL from - Github\ -- Assign the R project a short, informative name\ -- Choose where the new R Project will be saved locally\ -- Check "Open in new session" and click "Create project" + Github.\ +- Assign the R project a short, informative name.\ +- Choose where the new R Project will be saved locally.\ +- Check "Open in new session" and click "Create project". You are now in a new, local, RStudio project that is a clone of the @@ -341,15 +341,15 @@ linked. #### In Github Desktop {.unnumbered} -- Click on *File \> Clone a repository* +- Click on *File \> Clone a repository*. -- Select the URL tab +- Select the URL tab. -- Paste the HTTPS URL from Github in the first box +- Paste the HTTPS URL from Github in the first box. -- Select the folder in which you want to have your local repository +- Select the folder in which you want to have your local repository. -- Click "CLONE" +- Click "CLONE". ```{r echo=F, out.width = '100%', out.height='100%', fig.align = "center"} knitr::include_graphics(here::here("images", "github_clone_desktop.png")) @@ -361,8 +361,8 @@ An alternative setup scenario is that you have an existing R project with content, and you want to create a Github repository for it. 1) Create a new, empty Github repository for the project (see - instructions above)\ -2) Clone this repository locally (see HTTPS instructions above)\ + instructions above).\ +2) Clone this repository locally (see HTTPS instructions above).\ 3) Copy all the content from your pre-existing R project (codes, data, etc.) into this new empty, local, repository (e.g. use copy and paste).\ 4) Open your new project in RStudio, and go to the Git pane. The new files should @@ -388,17 +388,17 @@ Please note the buttons circled in the image above, as they will be referenced later (from left to right): - Button to *commit* the saved file changes to the local - branch (this will open a new window) + branch (this will open a new window). - Blue arrow to *pull* (update your local version of the branch with - any changes made on the remote/Github version of that branch) + any changes made on the remote/Github version of that branch). - Green arrow to *push* (send any commits/changes for your local version of the branch to the remote/Github version of that branch) -- The Git tab in RStudio +- The Git tab in RStudio. - Button to create a NEW branch using whichever local branch is shown to the right as the base. *You almost always want to branch off from - the main branch (after you first pull to update the main branch)* -- The branch you are currently working in -- Changes you made to code or other files will appear below + the main branch (after you first pull to update the main branch)*. +- The branch you are currently working in. +- Changes you made to code or other files will appear below. #### In Github Desktop {-} @@ -428,20 +428,20 @@ easy and fast. A typical workflow is as follow: 1. Make sure that your local repository is up-to-date, update it if - not + not. 2. Go to the branch you were working on previously, or create a new - branch to try out some things + branch to try out some things. 3. Work on the files locally on your computer, make one or several - commits to this branch + commits to this branch. -4. Update the remote version of the branch with your changes (push) +4. Update the remote version of the branch with your changes (push). 5. When you are satisfied with your branch, you can merge the online version of the working branch into the online "main" branch to - transfer the changes + transfer the changes. Other team members may be doing the same thing with their own branches, or perhaps contributing commits into your working branch as well. @@ -464,7 +464,7 @@ knitr::include_graphics(here::here("images", "GitHub-Flow.png")) ``` Image -[source](https://build5nines.com/introduction-to-git-version-control-workflow/) +[source](https://build5nines.com/introduction-to-git-version-control-workflow/). ## Create a new branch @@ -549,7 +549,7 @@ knitr::include_graphics(here::here("images", "github_tracking2.png")) You might be wondering what the yellow, blue, green, and red squares next to the file names represent. Here is a snapshot from the [RStudio -cheatsheet](https://www.rstudio.com/wp-content/uploads/2016/01/rstudio-IDE-cheatsheet.pdf) +cheatsheet](https://raw.githubusercontent.com/rstudio/cheatsheets/refs/heads/main/pngs/rstudio-ide.png) that explains their meaning. Note that changes with yellow "?" can still be staged, committed, and pushed. @@ -558,18 +558,18 @@ knitr::include_graphics(here::here("images", "github_tracking.png")) ``` - Press the "Commit" button in the Git tab, which will open a new - window (shown below) + window (shown below). -- Click on a file name in the upper-left box +- Click on a file name in the upper-left box. - Review the changes you made to that file (highlighted below in green - or red) + or red). - "Stage" the file, which will include those changes in the commit. Do this by checking the box next to the file name. Alternatively, you - can highlight multiple file names and then click "Stage" + can highlight multiple file names and then click "Stage". -- Write a commit message that is short but descriptive (required) +- Write a commit message that is short but descriptive (required). - Press the "Commit" button. A pop-up box will appear showing success or an error message. @@ -685,9 +685,9 @@ on Git commands. ***TIP:*** Asked to provide your password too often? See these chapters 10 & 11 of this -[tutorial](https://happygitwithr.com/credential-caching.html#credential-caching) +[tutorial](https://happygitwithr.com/ssh-keys) to connect to a repository using a SSH key (more -complicated) +complicated) . #### In Github Desktop {.unnumbered} @@ -817,9 +817,9 @@ github](https://github.com/tidyverse/dplyr/pulls). You can submit a pull request (PR) directly form the website (as illustrated bellow) or from Github Desktop. -- Go to Github repository (online) -- View the tab "Pull Requests" and click the "New pull request" button -- Select from the drop-down menu to merge your branch into main +- Go to Github repository (online). +- View the tab "Pull Requests" and click the "New pull request" button. +- Select from the drop-down menu to merge your branch into main. - Write a detailed Pull Request comment and click "Create Pull Request". @@ -906,12 +906,12 @@ a branch Be sure to also delete the branch locally on your computer. This will not happen automatically. -- From RStudio, make sure you are in the Main branch +- From RStudio, make sure you are in the Main branch. - Switch to typing Git commands in the RStudio "Terminal" (the tab adjacent to the R console), and type: **git branch -d branch_name**, where "branch_name" is the name of your branch to be - deleted -- Refresh your Git tab and the branch should be gone + deleted. +- Refresh your Git tab and the branch should be gone. #### In Github Desktop @@ -1059,7 +1059,7 @@ website](https://learngitbranching.js.org/). You enter commands in a Git shell. -*Option 1* You can open a new Terminal in RStudio. This tab is next to +*Option 1*: You can open a new Terminal in RStudio. This tab is next to the R Console. If you cannot type any text in it, click on the drop-down menu below "Terminal" and select "New terminal". Type the commands at the blinking space in front of the dollar sign "\$". @@ -1068,12 +1068,12 @@ commands at the blinking space in front of the dollar sign "\$". knitr::include_graphics(here::here("images", "github_terminal.png")) ``` -*Option 2* You can also open a *shell* (a terminal to enter commands) by +*Option 2*: You can also open a *shell* (a terminal to enter commands) by clicking the blue "gears" icon in the Git tab (near the RStudio Environment). Select "Shell" from the drop-down menu. A new window will open where you can type the commands after the dollar sign "\$". -*Option 3* Right click to open "Git Bash here" which will open the same +*Option 3*: Right click to open "Git Bash here" which will open the same sort of terminal, or open *Git Bash* form your application list. [More beginner-friendly informations on Git Bash](https://happygitwithr.com/shell.html), how to find it and some bash commands you will need. @@ -1118,32 +1118,33 @@ The [Github.com documentation and start guide](https://docs.github.com/en/github). The RStudio ["IDE" -cheatsheet](https://www.rstudio.com/wp-content/uploads/2016/01/rstudio-IDE-cheatsheet.pdf) +cheatsheet](https://rstudio.github.io/cheatsheets/html/rstudio-ide.html) which includes tips on Git with RStudio. - +[GitHub: A beginner's guide to going back in time (aka fixing mistakes)](https://ohi-science.org/news/github-going-back-in-time) **Git commands for beginners** An [interactive -tutorial](learngitbranching.js.org) to learn +tutorial](https://learngitbranching.js.org/) to learn Git commands. -: +[Git for Absolute Beginners](https://www.freecodecamp.org/news/an-introduction-to-git-for-absolute-beginners-86fa1d32ff71) good for learning the absolute basics to track changes in one folder on you own computer. -Nice schematics to understand branches: - +Nice schematics to [understand branches](https://speakerdeck.com/alicebartlett/git-for-humans) **Tutorials covering both basic and more advanced subjects** - +[Learn Git in 30 Minutes](https://tutorialzine.com/2016/06/learn-git-in-30-minutes) - - (short course) - +[Commands and Operations in Git](https://dzone.com/articles/git-tutorial-commands-and-operations-in-git) + +[Version Control with Git (short course)](https://swcarpentry.github.io/git-novice/) + +[Introduction to Git (book)](https://rsjakob.gitbooks.io/git/content/chapter1.html) The [Pro Git book](https://git-scm.com/book/en/v2) is considered an official reference. While some chapters are ok, it is usually a bit _technical_. It is probably a good resource diff --git a/new_pages/reportfactory.qmd b/new_pages/reportfactory.qmd index 2a9b309..4425d63 100644 --- a/new_pages/reportfactory.qmd +++ b/new_pages/reportfactory.qmd @@ -19,7 +19,6 @@ You can do this via the **pacman** package with `p_load_current_gh()` which will ```{r, eval=FALSE} # Install and load the latest version of the package from Github pacman::p_load_current_gh("reconverse/reportfactory") -#remotes::install_github("reconverse/reportfactory") # alternative ``` @@ -27,9 +26,8 @@ pacman::p_load_current_gh("reconverse/reportfactory") To create a new factory, run the function `new_factory()`. This will create a new self-contained R project folder. By default: -* The factory will be added to your working directory -* The name of the factory R project will be called "new_factory.Rproj" -* Your RStudio session will "move in" to this R project +* The factory will be added to your working directory. +* The name of the factory R project will be called "new_factory.Rproj". * Your RStudio session will "move in" to this R project. ```{r, eval=F} # This will create the factory in the working directory @@ -43,23 +41,23 @@ Looking inside the factory, you can see that sub-folders and some files were cre knitr::include_graphics(here::here("images", "factory_new2.png")) ``` -* The *report_sources* folder will hold your R Markdown scripts, which generate your reports -* The *outputs* folder will hold the report outputs (e.g. HTML, Word, PDF, etc.) -* The *scripts* folder can be used to store other R scripts (e.g. that are sourced by your Rmd scripts) -* The *data* folder can be used to hold your data ("raw" and "clean" subfolders are included) -* A *.here* file, so you can use the **here** package to call files in sub-folders by their relation to this root folder (see [R projects](r_projects.qmd) page for details) -* A *gitignore* file was created in case you link this R project to a Github repository (see [Version control and collaboration with Github](collaboration.qmd)) -* An empty README file, for if you use a Github repository +* The *report_sources* folder will hold your R Markdown scripts, which generate your reports. +* The *outputs* folder will hold the report outputs (e.g. HTML, Word, PDF, etc.). +* The *scripts* folder can be used to store other R scripts (e.g. that are sourced by your Rmd scripts). +* The *data* folder can be used to hold your data ("raw" and "clean" subfolders are included). +* A *.here* file, so you can use the **here** package to call files in sub-folders by their relation to this root folder (see [R projects](r_projects.qmd) page for details). +* A *gitignore* file was created in case you link this R project to a Github repository (see [Version control and collaboration with Github](collaboration.qmd)). +* An empty README file, for if you use a Github repository. -**_CAUTION:_** depending on your computer's setting, files such as ".here" may exist but be invisible. +**_CAUTION:_** depending on your computer's setting, files such as ".here" may exist but be invisible. To see hidden files, please follow the steps [here if you have a Windows computer](https://support.microsoft.com/en-us/windows/show-hidden-files-0320fe58-0117-fd59-6851-9b7f9840fdb2), and [here if you use a Mac](https://www.pcmag.com/how-to/how-to-access-your-macs-hidden-files). Of the default settings, below are several that you might want to adjust within the `new_factory()` command: -* `factory = ` - Provide a name for the factory folder (default is "new_factory") -* `path = ` - Designate a file path for the new factory (default is the working directory) -* `report_sources = ` Provide an alternate name for the subfolder which holds the R Markdown scripts (default is "report_sources") -* `outputs = ` Provide an alternate name for the folder which holds the report outputs (default is "outputs") +* `factory = ` - Provide a name for the factory folder (default is "new_factory"). +* `path = ` - Designate a file path for the new factory (default is the working directory). +* `report_sources = ` Provide an alternate name for the subfolder which holds the R Markdown scripts (default is "report_sources"). +* `outputs = ` Provide an alternate name for the folder which holds the report outputs (default is "outputs"). See `?new_factory` for a complete list of the arguments. @@ -87,8 +85,8 @@ knitr::include_graphics(here::here("images", "factory_overview.png")) From within the factory R project, create a R Markdown report just as you would normally, and save it into the "report_sources" folder. See the [R Markdown](rmarkdown.qmd) page for instructions. For purposes of example, we have added the following to the factory: -* A new R markdown script entitled "daily_sitrep.Rmd", saved within the "report_sources" folder -* Data for the report ("linelist_cleaned.rds"), saved to the "clean" sub-folder within the "data" folder +* A new R markdown script entitled "daily_sitrep.Rmd", saved within the "report_sources" folder. +* Data for the report ("linelist_cleaned.rds"), saved to the "clean" sub-folder within the "data" folder. We can see using `factory_overview()` our R Markdown in the "report_sources" folder and the data file in the "clean" data folder (highlighted): @@ -104,8 +102,8 @@ knitr::include_graphics(here::here("images", "factory_new_rmd.png")) In this simple script, there are commands to: -* Load necessary packages -* Import the linelist data using a filepath from the **here** package (read more in the page on [Import and export](importing.qmd)) +* Load necessary packages. +* Import the linelist data using a filepath from the **here** package (read more in the page on [Import and export](importing.qmd)). ```{r, eval=F} linelist <- import(here("data", "clean", "linelist_cleaned.rds")) @@ -216,11 +214,11 @@ knitr::include_graphics(here::here("images", "factory_overview_all.png")) ``` -* Within "outputs", sub-folders have been created for each Rmd report -* Within those, further sub-folders have been created for each unique compiling - * These are date- and time-stamped ("2021-04-23_T11-07-36" means 23rd April 2021 at 11:07:36) - * You can edit the date/time-stamp format. See `?compile_reports` -* Within each date/time compiled folder, the report output is stored (e.g. HTML, PDF, Word) along with the Rmd script (version control!) and any other exported files (e.g. table.csv, epidemic_curve.png) +* Within "outputs", sub-folders have been created for each Rmd report. +* Within those, further sub-folders have been created for each unique compiling. + * These are date- and time-stamped ("2021-04-23_T11-07-36" means 23rd April 2021 at 11:07:36). + * You can edit the date/time-stamp format. See `?compile_reports`. +* Within each date/time compiled folder, the report output is stored (e.g. HTML, PDF, Word) along with the Rmd script (version control!) and any other exported files (e.g. table.csv, epidemic_curve.png). Here is a view inside one of the date/time-stamped folders, for the "daily_sitrep" report. The file path is highlighted in yellow for emphasis. @@ -257,8 +255,8 @@ We encourage you to utilize the "scripts" folder to store "runfiles" or .R scrip * With **reportfactory**, you can use the function `list_deps()` to list all packages required across all the reports in the entire factory. * There is an accompanying package in development called **rfextras** that offers more helper functions to assist you in building reports, such as: - * `load_scripts()` - sources/loads all .R scripts in a given folder (the "scripts" folder by default) - * `find_latest()` - finds the latest version of a file (e.g. the latest dataset) + * `load_scripts()` - sources/loads all .R scripts in a given folder (the "scripts" folder by default). + * `find_latest()` - finds the latest version of a file (e.g. the latest dataset). @@ -266,7 +264,7 @@ We encourage you to utilize the "scripts" folder to store "runfiles" or .R scrip ## Resources { } -See the **reportfactory** package's [Github page](https://github.com/reconverse/reportfactory) +See the **reportfactory** package's [Github page](https://github.com/reconverse/reportfactory). -See the **rfextras** package's [Github page](https://github.com/reconhub/rfextras) +See the **rfextras** package's [Github page](https://github.com/reconhub/rfextras).