In the previous lesson, you saw how to leverage both RPubs and GitHub to publish examples of the types of documents that can be produced using your reproducible templates. We did this by providing web links in your README file on your GitHub repository. However, simply providing examples of your reports is not enough. You should also provide the following information to people using your templates. Number one, what kind of data and format does your report template expect. For example, the weather article needed the weather check data set that was built into the 538 R package. Number two, the file components that are needed to support your template. For example, the WC base RND template document assumes that the components are contained in three sub folders for text, images, and code. Number three, you need descriptions of each of the document components, what is actually in each file, and what the purpose of that file is. And number four, it's always good to provide instructions to people wanting to use your templates of any assumptions or dependencies that they need to know? For example, can a child text documents or the child R scripts be used in any order? In our example for the WC base template we could easily switch the order of the two child text documents that swap the order of the purpose and the background. For example, the purpose could come before the background section. Likewise, we could switch the order of the R scripts such that the R code that makes the clustered bar chart could come before the code that makes the demographics table. However, both of these R scripts assume that the set-up script had already been run, because that loads the R packages and the weather-check dataset. So the set-up script has to come first at the beginning of the document. It would be good to include these kinds of instructions in your README file. I'm going to leave this as an exercise to do on your own. But take some time to customize your README file. You may also want to share these instructions with a colleague or a friend, and see if they can follow your instructions well enough to use your GitHub repository and the associated files to build their own reports using your template and instructions. Some other ways to communicate to people how to use your templates can be accomplished by providing vignettes. And you can do this through our packages. You can learn more about creating R packages and specifically about adding a vignettes to your R package at Karl Broman's tutorial on writing vignettes. And the link was provided in the read ahead materials. So let's add a vignettes to your WCTemplatePackage. And we created this in module four. So let's open RStudio and we're going to open that project for WCTemplatePackage. Let's open a file explorer window and go to RepTemplates for your WCTemplatePackage. And in this folder we're going to create a new subfolder called vignettes. And then in this folder we're actually going to copy over the wcArticle file from your WCtemplateSimple project and we're going to paste it in the WCtemplatePackage for vignettes. After you've got a copy of the wcArticle in your vignettes folder go ahead and open it here in RStudio edit window. To make this work as a vignette we actually have to make some edits to the YAML header. For right now, we don't need all of these parameters. So we're actually going to go in and delete the choices and input select and just delete that from the button of your YAML header information. For right now, we're just going to leave this set where the region is set to the value for mountain. The next change that we need to make to the YAML header is we're going to change the output from HTML document to vignette document. We can take a look at what Karl Broman has here in his tutorial. So we're actually going to change the output, and we need to add some code here on how to build the vignette. We're actually going to add this to the bottom of the YAML header, and we're going to remove the previous output statement for HTML document. Go ahead and click save. Now that we've made these changes to the wcArticle rmarkdown file, we also need to make some change to the description file. Open your description file, and at the bottom we need to add two more lines. We need to add in a line for suggests that lists the knitr and rmarkdown packages and a line for VignetteBuilder that says to use the knitr package to build the vignettes, click save. Now that we've made the changes to the description and the wcArticle rmarkdown file, we need to next build the vignettes for your package. We're going to do that by typing a command Into the console window into RStudio. devtools build_vignettes. When you click this it begins building the vignettes for your package. When it completes you'll notice that is says that it was copying some information into a new folder under ints/doc. So if we click on the ints folder in addition to the rmarkdown folder that we had previously. We now have a folder for doc, and there's three new files. We have an HTML, an R, and the rmarkdown file for the wcArticle. These have now been added to your package. Let's go ahead and use Git Bash to sync these up with the changes to the repository. Make sure that you're in the folder for your WCtemplatePackage and typing git status to see the changes that you've made. Type git add to add the files, git commit and we'll say that we've added the vignette. Type in git push to sync everything up with your cloud account and then type git status. So go back to the GitHub repository for your WCtemplatePackage. And click refresh to see the updates that were just added. Now that we've made all these changes to your package, we're going to re-install it with the updated vignette. We're going to use the devtools command for installing off of a GitHub repository, so let's type in devtools::install_github. Make sure that you use the link for your GitHub account. In our studio, go ahead and click on the packages tab and scroll down to where you can see the WCtemplatePackage installed. If you click on this link, it brings up the help file for your package. At the top, you're going to see a link for user guides, package vignettes, and other documentation. And when you click on this, it brings up a page that lists any vignettes that come with your package. If you had more than one, they'd be listed right here. Let's go ahead and click on the link for the wcArticle to see the HTML for this template. This now is the vignette for your package. This is just a quick example. But you could spend some time developing rmarkdown files to create different vignettes that illustrate different types of templates or layouts and options that are possible with your R package. One example to get ideas is the CRAN website for the dplyr package. When you bring this up, you'll notice that there's a listing here for vignettes. They actually have five. These five vignettes illustrate different capabilities of the dplyr package. Back in RStudio we can click on packages and scroll to the link for the dplyr package. And again, if we click on user guides package of vignettes and other documentation. Again, you'll see these same five vignettes listed here in the help window. So now you've learned three different ways of communicating information and instructions to others on how to use your templates and packages. You can publish examples using RPubs. You can use HTML files using GitHub pages and docs folder of your GitHub repository. And if you convert your template project into an R package, you can use vignettes to illusrtate how to use your package. And through the R package, you really have a fourth way of communicating, through the template itself, which is available to others when they create a new rmarkdown template after they install your package. So the template itself can actually provide instructions and details on how to use your template.
