This vignette is for those users that already have an existing project and wish to incorporate workflowr to create a research website. Migrating an existing project to use workflowr varies from straightforward to difficult depending on the scenario and your comfort level with Git. This vignette assumes that you have the background knowledge of workflowr explained in the Getting started vignette. Even if you have no need for a new workflowr project, please run through that vignette first as an exercise to familiarize yourself with the workflowr philosophy and functions.
vignette("wflow-01-getting-started", "workflowr")If you have a collection of R Markdown files, but no version control or other files, the most straightforward solution would be to create a workflowr project in a new directory and then move the R Markdown files to the analysis/ subdirectory. In the hypothetical example below, the original R Markdown files are located in the directory ~/projects/misc/ and the workflowr project will be created in the new directory ~/projects/new-project/.
library("workflowr")
# Create project directory and change working directory to this location
wflow_start("~/projects/new-project")
# Copy the files to the analysis subdirectory of the workflowr project
file.copy(from = Sys.glob("~/projects/misc/*Rmd"), to = "analysis")Next update your R Markdown files to use the workflowr template (you can first run wflow_update() with no arguments to preview the potential changes).
wflow_update(dry_run = FALSE)Lastly, build and commit the website using wflow_publish():
wflow_publish("analysis/*Rmd", "Publish analysis files")If your project already has lots of infrastructure, it is most convenient to add the workflowr files directory to your already existing directory. This is controlled with the argument existing. In the hypothetical example below, the existing project is located at ~/projects/mature-project/.
library("workflowr")
wflow_start("~/projects/mature-project", existing = TRUE)The above command will add the workflowr files to your existing project and also commit them to version control (it will initialize a Git repo if it doesn’t already exist). If you’d prefer to not use version control for your project or you’d prefer to commit the workflowr files yourself manually, you can set git = FALSE (this is also useful if you want to first test to see what would happen without committing the results).
By default wflow_start() will not overwrite your existing files (e.g. if you already have a README.md). If you’d prefer to overwrite your files with the default workflowr files, set overwrite = TRUE.
To add your R Markdown files to the research website, you can move them to the subdirectory analysis/ (note you can do this before or after running wflow_start()).
Next run wflow_update() to convert the R Markdown files to use the workflowr template:
wflow_update(dry_run = FALSE)Lastly, build and commit the website using wflow_publish():
wflow_publish("analysis/*Rmd", "Publish analysis files")If your project is organized as an R package, you can still add a website using workflowr. In the hypothetical example below, the existing package is located at ~/projects/my-package/.
library("workflowr")
wflow_start("~/projects/my-package", existing = TRUE)The above command will add the workflowr files to your existing project and also commit them to version control (it will initialize a Git repo if it doesn’t already exist). If you’d prefer to not use version control for your project or you’d prefer to commit the workflowr files yourself manually, you can set git = FALSE (this is also useful if you want to first test to see what would happen without committing the results).
You’ll want R to ignore the workflowr directories when building the R package. Thus add the following to the .Rbuildignore file:
^analysis$
^docs$
^data$
^code$
^output$If your primary purpose for creating a website to accompany your package is to share the package documentation, please check out the package pkgdown. It creates a website from the vignettes and function documentation files (i.e. the Rd files in man/). In contrast, if the purpose of the website is to demonstrate results you obtained using the package, use workflowr.
If your project uses the ashlar template, you’ll need to follow multiple steps to convert it to a valid workflowr setup.
First, make sure you are in the “master” branch. Also, you should run the following Git commands from the base of the project directory.
git checkout masterIf you have any HTML files in analysis/ remove them using Git at the command line.
git rm analysis/*htmlNext remove the other ashlar infrastructure files.
git rm analysis/chunk-options.R analysis/Makefile analysis/_output.yaml
git rm -r analysis/libs analysis/include analysis/figureModify .gitignore so that it ignores HTML and figure files in analysis/ only by changing *html to analysis/*html and *png to analysis/figure. Afterwards add the file.
nano .gitignore
git add .gitignoreAnd move the RStudio project file from analysis/ to the base of the project.
git mv analysis/*Rproj .Commit these changes.
git commit -m "Removed ashlar infrastructure."Next open R to add the workflowr files. In the hypothetical example below, the existing package is located at ~/projects/ashlar-project/.
library("workflowr")
wflow_start("~/projects/ashlar-project", existing = TRUE)This will generate a few warning messages stating that the directory already contains a .git directory and a .gitignore file. These can be safely ignored because ashlar projects are expected to be using Git for version control.
Lastly, you’ll need to update your R Markdown files to use the workflowr template, which you can do using the function wflow_update():
wflow_update()
# Run with `dry_run = FALSE` to apply the updates
# wflow_update(dry_run = FALSE)This will update every R Markdown file, with the exception of index.Rmd, about.Rmd, and license.Rmd. It will also fail to automatically convert any ashlar files that do not follow the template (e.g. they do not have the sessionInfo() chunk), so you will have to manually update these files. Also, workflowr no longer includes the date and SHA1 in the organizational files like index.Rmd, so you can remove this manually if you like.
Now you should have a functioning workflowr project! From here you should be able to make a few more small edits and then follow the workflowr steps to create your website:
analysis/_site.yml so that the GitHub URL points to your repository (and commit the change)wflow_publish("analysis/*Rmd", "Publish files using workflowr")) to build and commit the website files