Elaborate on rmd files #28

- describe how objects are passed around between rmd files.

inst/extdata/tests/extra.rmd

@@ -9,35 +9,29 @@ output: html_document
 knitr::opts_chunk$set(echo = TRUE)
 ```
 
-## R Markdown
+This file is processed second in the `config.yml` file. It therefore has access to the data objects
+created by `subsetCars.Rmd`, the file that is processed first in the `config.yml`.
 
-This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
+## Reading objects from previously run files
 
-When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
+In order to read previously processed objects, we use the `datapackager_object_read()` API from `DataPackageR`:
 
-```{r cars}
-summary(cars)
-```
-
-## Reading objects from previously run files
 
 ```{r reading_from_environments}
 library(DataPackageR)
 cars_over_20 = datapackager_object_read("cars_over_20")
 print(cars_over_20)
-f = function(){
-  datapackager_object_read("cars_over_20")
-}
-print(f())
 ```
 
-## Including Plots
+This API reads from an environment named `ENVS`, containing `subsetCars` and any other previously built data set objects. It is passed into the render environment of `extra.rmd` by DataPackageR at the `render()` call. 
+
+## Additional data objects
 
-You can also embed plots, for example:
+This file will add the pressure data set to the example.
 
-```{r pressure, echo=FALSE}
+```{r}
+data(pressure)
+pressure <- pressure # need to do an assignment
 plot(pressure)
-pressure=pressure
 ```
 
-Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.

inst/extdata/tests/subsetCars.Rmd

@@ -1,5 +1,5 @@
 ---
-title: "Test DataPackageR"
+title: "A Test Document for DataPackageR"
 author: "Greg Finak"
 output: html_document
 ---
@@ -8,19 +8,52 @@ output: html_document
 knitr::opts_chunk$set(echo = TRUE)
 ```
 
-## R Markdown
+This is a simple Rmd file that demonstrates how DataPackageR processes Rmarkdown files and creates data sets
+that are then stored in an R data package. 
 
-This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.
+In the `config.yml` for this example, this file is listed first, and therefore processed first.
 
-When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
+This particular document simply subsets the `cars` data set:
 
 ```{r cars}
 summary(cars)
+dim(cars)
 ```
 
-Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.
+`cars` consists of a data frame of 50 rows and two columns. The `?cars` documentation specifies that it consists of speed and stopping distances of cars.
+
+Let's say, for some reason, we are only interested in the stopping distances of cars traveling greater than 20 miles per hour.
 
 ```{r}
 cars_over_20 = subset(cars, speed > 20)
 ```
 
+The data frame `cars_over_20` now holds this information. 
+
+# Storing data set objects and making making accessible to other processing scripts. 
+
+When DataPackageR processes this file, it creates this `cars_over_20` object. After processing the file it does several things:
+
+1. It compares the objects in the rmarkdown render environment of `subsetCars.Rmd` against the objects listed in the `config.yml` file `objects` property. 
+2. It finds `cars_over_20` is listed there, so it stores it in a new environment.
+3. That environment is passed to subsequent R and Rmd files. Specifically when the `extra.rmd` file is processed, it has access to an environment object that holds all the `objects` (defined in the yaml config) that have already been created and processed. This environment is passed into subsequent scripts at the `render()` call. 
+
+All of the above is done automatically. The user only needs to list the objects to be stored and passed to other scripts in the `config.yml` file. 
+
+The `datapackager_object_read()` API can be used to retrieve these objects from the environment. 
+
+### Storing objects in the data package
+
+In addition to passing around an environment to subsequent scripts, the `cars_over_20` object is stored in the data package `/data` directory as an `rda` file. 
+
+Note that this is all done automatically. The user does not need to explicitly save anything, they only need to list the objects to be store in the `config.yml`. 
+
+This object is then accessible in the resulting package via the `data()` API, and its documentation is accessible via `?cars_over_20`. 
+
+### Data object documentation
+
+The documentation for the `cars_over_20` object is created in a `subsetCars.R` file in the `/R` directory of the data package. 
+
+While the data object document stub is created automatically, it must be edited by the user to provide additional details about the data object.
+
+