Take the best of both README templates

NEWS.md

@@ -1,5 +1,7 @@
 # devtools 1.12.0.9000
 
+* `use_readme_rmd()` and `use_readme()` share a common template with sections for package overview, GitHub installation (if applicable), and an example (@jennybc, #1287).
+
 * `test()` doesn't load helpers twice anymre (@krlmlr, #1256).
 
 * fix auto download method selection for `install_github()` on R 3.1 which

R/infrastructure.R

@@ -466,18 +466,36 @@ use_build_ignore <- function(files, escape = TRUE, pkg = ".") {
 
 #' Create README files.
 #'
+#' Creates skeleton README files with sections for
+#' \itemize{
+#' \item a high-level description of the package and its goals
+#' \item R code to install from GitHub, if GitHub usage detected
+#' \item a basic example
+#' }
 #' Use \code{Rmd} if you want a rich intermingling of code and data. Use
 #' \code{md} for a basic README. \code{README.Rmd} will be automatically
-#' added to \code{.Rbuildignore}.
+#' added to \code{.Rbuildignore}. The resulting README is populated with default
+#' YAML frontmatter and R fenced code blocks (\code{md}) or chunks (\code{Rmd}).
 #'
 #' @param pkg package description, can be path or package name.  See
 #'   \code{\link{as.package}} for more information
 #' @export
+#' @examples
+#' \dontrun{
+#' use_readme_rmd()
+#' use_readme_md()
+#' }
 #' @family infrastructure
 use_readme_rmd <- function(pkg = ".") {
   pkg <- as.package(pkg)
 
-  use_template("README.Rmd", ignore = TRUE, open = TRUE, pkg = pkg)
+  if (uses_github(pkg$path)) {
+    pkg$github <- github_info(pkg$path)
+  }
+  pkg$Rmd <- TRUE
+
+  use_template("omni-README", save_as = "README.Rmd", data = pkg,
+               ignore = TRUE, open = TRUE, pkg = pkg)
   use_build_ignore("^README-.*\\.png$", escape = FALSE, pkg = pkg)
 
   if (uses_git(pkg$path) && !file.exists(pkg$path, ".git", "hooks", "pre-commit")) {
@@ -497,7 +515,8 @@ use_readme_md <- function(pkg = ".") {
     pkg$github <- github_info(pkg$path)
   }
 
-  use_template("README.md", data = pkg, open = TRUE, pkg = pkg)
+  use_template("omni-README", save_as = "README.md",
+               data = pkg, open = TRUE, pkg = pkg)
 }
 
 #' Use NEWS.md
@@ -724,7 +743,7 @@ use_template <- function(template, save_as = template, data = list(),
 
   if (open) {
     message("* Modify `", save_as, "`.")
-    open_in_rstudio(save_as)
+    open_in_rstudio(path)
   }
 
   invisible(TRUE)

inst/templates/omni-README

@@ -0,0 +1,54 @@
+{{#Rmd}}
+---{{#github}}
+output: github_document
+{{/github}}
+{{#^github}}
+output:
+  md_document:
+    variant: markdown_github
+{{/github}}
+---
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+```{r, echo = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.path = "README-"
+)
+```
+
+{{/Rmd}}
+
+# {{{ package }}}
+
+The goal of {{{package}}} is to ...
+
+{{#github}}
+## Installation
+
+You can install {{{ package }}} from github with:
+
+{{#Rmd}}
+```{r gh-installation, eval = FALSE}
+{{/Rmd}}
+{{^Rmd}}
+``` r
+{{/Rmd}}
+# install.packages("devtools")
+devtools::install_github("{{{repo}}}/{{{username}}}")
+```
+
+{{/github}}
+## Example
+
+This is a basic example which shows you how to solve a common problem:
+
+{{#Rmd}}
+```{r example}
+{{/Rmd}}
+{{^Rmd}}``` r
+{{/Rmd}}
+## basic example code
+```

tests/testthat/infrastructure/README.Rmd

@@ -1,5 +1,7 @@
 ---
-output: github_document
+output:
+  md_document:
+    variant: markdown_github
 ---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
@@ -11,3 +13,15 @@ knitr::opts_chunk$set(
   fig.path = "README-"
 )
 ```
+
+# infrastructure
+
+The goal of infrastructure is to ...
+
+## Example
+
+This is a basic example which shows you how to solve a common problem:
+
+```{r example}
+## basic example code
+```

tests/testthat/infrastructure/README.md

@@ -6,6 +6,7 @@ The goal of infrastructure is to ...
 
 This is a basic example which shows you how to solve a common problem:
 
-```R
-...
+
+``` r
+## basic example code
 ```