build vignettes.

inst/doc/YAML_CONFIG.R

@@ -1,8 +1,7 @@
 ## ---- echo = FALSE, results = 'hide'-------------------------------------
 library(DataPackageR)
 library(yaml)
-yml <- DataPackageR::construct_yml_config(code = "subsetCars.Rmd",
-                                          data = "cars_over_20")
+yml <- DataPackageR::construct_yml_config(code = "subsetCars.Rmd", data = "cars_over_20")
 
 ## ---- echo = FALSE, comment=""-------------------------------------------
 cat(yaml::as.yaml(yml))

inst/doc/YAML_CONFIG.html

@@ -12,7 +12,7 @@
 
 <meta name="author" content="Greg Finak [email protected]" />
 
-<meta name="date" content="2018-07-31" />
+<meta name="date" content="2018-08-01" />
 
 <title>The DataPackageR YAML configuration file.</title>
 
@@ -280,7 +280,7 @@
 
 <h1 class="title toc-ignore">The DataPackageR YAML configuration file.</h1>
 <h4 class="author"><em>Greg Finak <a href="mailto:[email protected]">[email protected]</a></em></h4>
-<h4 class="date"><em>2018-07-31</em></h4>
+<h4 class="date"><em>2018-08-01</em></h4>
 
 
 <div id="TOC">
@@ -309,7 +309,7 @@ <h2>The <code>datapackager.yml</code> file.</h2>
       enabled: yes
   objects: cars_over_20
   render_root:
-    tmp: '138283'</code></pre>
+    tmp: '978673'</code></pre>
 </div>
 <div id="yaml-config-file-properties." class="section level2">
 <h2>YAML config file properties.</h2>
@@ -399,7 +399,7 @@ <h5>Example</h5>
       enabled: no
   objects: cars_over_20
   render_root:
-    tmp: '739294'</code></pre>
+    tmp: '756425'</code></pre>
 </div>
 </div>
 <div id="yml_enable_compile" class="section level4">
@@ -416,7 +416,7 @@ <h5>Example</h5>
       enabled: yes
   objects: cars_over_20
   render_root:
-    tmp: '739294'</code></pre>
+    tmp: '756425'</code></pre>
 </div>
 </div>
 <div id="yml_add_files" class="section level4">
@@ -435,7 +435,7 @@ <h5>Example</h5>
       enabled: yes
   objects: cars_over_20
   render_root:
-    tmp: '739294'</code></pre>
+    tmp: '756425'</code></pre>
 </div>
 </div>
 <div id="yml_add_objects" class="section level4">
@@ -456,7 +456,7 @@ <h5>Example</h5>
   - cars_over_20
   - another_object
   render_root:
-    tmp: '739294'</code></pre>
+    tmp: '756425'</code></pre>
 </div>
 </div>
 <div id="yml_remove_files" class="section level4">
@@ -475,7 +475,7 @@ <h5>Example</h5>
   - cars_over_20
   - another_object
   render_root:
-    tmp: '739294'</code></pre>
+    tmp: '756425'</code></pre>
 </div>
 </div>
 <div id="yml_remove_objects" class="section level4">
@@ -492,7 +492,7 @@ <h5>Example</h5>
       enabled: yes
   objects: cars_over_20
   render_root:
-    tmp: '739294'</code></pre>
+    tmp: '756425'</code></pre>
 </div>
 </div>
 <div id="yml_write" class="section level4">

inst/doc/usingDataPackageR.R

@@ -26,7 +26,9 @@ DataPackageR::datapackage_skeleton(name = "mtcars20",
   force = TRUE,
   code_files = processing_code,
   r_object_names = "cars_over_20",
-  path = tempdir()
+  path = tempdir() 
+  #dependencies argument is empty
+  #raw_data_dir argument is empty.
   ) 
 
 ## ----dirstructure,echo=FALSE---------------------------------------------
@@ -42,8 +44,7 @@ df <- data.frame(pathString = file.path(
 as.Node(df)
 
 ## ---- echo=FALSE---------------------------------------------------------
-cat(yaml::as.yaml(yaml::yaml.load_file(
-  file.path(tempdir(),"mtcars20","datapackager.yml"))))
+cat(yaml::as.yaml(yaml::yaml.load_file(file.path(tempdir(),"mtcars20","datapackager.yml"))))
 
 ## ----eval=TRUE-----------------------------------------------------------
 # Run the preprocessing code to build cars_over_20
@@ -61,11 +62,13 @@ df <- data.frame(pathString = file.path(
   ))
   as.Node(df)
 
+## ----rebuild_docs--------------------------------------------------------
+document(file.path(tempdir(),"mtcars20"))
+
 ## ------------------------------------------------------------------------
 # Let's use the package we just created.
-install.packages(file.path(tempdir(),"mtcars20_1.0.tar.gz"),
-                 type = "source", repos = NULL)
-if (!"package:mtcars20" %in% search())
+install.packages(file.path(tempdir(),"mtcars20_1.0.tar.gz"), type = "source", repos = NULL)
+if(!"package:mtcars20"%in%search())
   attachNamespace('mtcars20') #use library() in your code
 data("cars_over_20") # load the data
 

inst/doc/usingDataPackageR.Rmd

@@ -41,7 +41,8 @@ The user needs to provide:
 
 - R or Rmd code files that do data processing.
 - A list of R object names created by those code files.
-
+- Optionally a path to a directory of raw data (will be copied into the package).
+- Optionally a list of additional code files that may be dependencies of your R scripts. 
 
 
 ```{r minimal_example, results='hide'}
@@ -65,7 +66,9 @@ DataPackageR::datapackage_skeleton(name = "mtcars20",
   force = TRUE,
   code_files = processing_code,
   r_object_names = "cars_over_20",
-  path = tempdir()
+  path = tempdir() 
+  #dependencies argument is empty
+  #raw_data_dir argument is empty.
   ) 
 ```
 
@@ -120,9 +123,11 @@ Further information on the contents of the YAML configuration file, and the API
 
 Raw data (provided the size is not prohibitive) can be placed in `inst/extdata`.
 
+The `datapackage_skeleton()` API has the `raw_data_dir` argument, which will copy the contents of `raw_data_dir`  (and its subdirectories) into `inst/extdata` automatically. 
+
 In this example we are reading the `mtcars` data set that is already in memory, rather than from the file system.
 
-#### An API to read raw data sets from within an R or Rmd procesing script.
+### An API to read raw data sets from within an R or Rmd procesing script.
 
 As stated in the README, in order for your processing scripts to be portable, you should not use abosolute paths to files. 
 DataPackageR provides an API to point to the data package root directory and the `inst/extdata` and `data` subdirectories.
@@ -139,6 +144,23 @@ Similarly:
 
 Raw data sets that are stored externally (outside the data package source tree) can be constructed relative to the `project_path()`.
 
+### YAML header metadata for R files and Rmd files.
+
+If your processing scripts are Rmd files, the usual yaml header for rmarkdown documents should be present.
+
+If you have Rmd files, you can still include a yaml header, but it should be commented with `#'` and it should be at the top of your R file. For example, a test R file in the DataPackageR package looks as follows:
+
+```
+#'---
+#'title: Sample report  from R script
+#'author: Greg Finak
+#'date: August 1, 2018
+#'---
+data <- runif(100)
+```
+
+This will be converted to an Rmd file with a proper yaml header, which will then be turned into a vignette and properly indexed in the built package.
+
 
 ## Build the data package.
 
@@ -150,6 +172,21 @@ Once the skeleton framework is set up,
 DataPackageR:::package_build(file.path(tempdir(),"mtcars20"))
 ```
 
+### Documenting your data set changes in NEWS.md
+
+When you build a package in interactive mode, you will be
+prompted to input text describing the changes to your data package (one line). 
+
+These will appear in the NEWS.md file in the following format:
+
+```
+DataVersion: xx.yy.zz
+========
+A description of your changes to the package
+
+[The rest of the file]
+```
+
 
 ### Why not just use R CMD build?
 
@@ -183,12 +220,22 @@ df <- data.frame(pathString = file.path(
   as.Node(df)
 ```
 
-#### Update the autogenerated documentation. 
+### Update the autogenerated documentation. 
 
 After the first build, the `R` directory contains `mtcars.R` that has autogenerated `roxygen2` markup documentation for the data package and for the packaged data `cars_over20`. 
 
 The processed `Rd` files can be found in `man`. 
 
+The autogenerated documentation source is in the `documentation.R` file in `data-raw`. 
+
+You should update this file to properly document your objects. Then rebuild the documentation:
+
+```{r rebuild_docs}
+document(file.path(tempdir(),"mtcars20"))
+```
+
+This is done without reprocessing the data.
+
 #### Dont' forget to rebuild the package.
 
 You should update the documentation in `R/mtcars.R`, then call `package_build()` again.