diff --git a/DESCRIPTION b/DESCRIPTION index f190dd5..e8cf600 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Package: rocco Type: Package Title: rocco (http://github.com/robertzk/rocco) Description: Literate Documentation Generator for R. -Version: 0.1.0 +Version: 0.1.1 Author: Robert Krzyzanowski Maintainer: Robert Krzyzanowski Authors@R: c(person("Robert", "Krzyzanowski", @@ -13,7 +13,7 @@ License: MIT LazyData: true Imports: whisker, - markdown + markdown Suggests: knitr, microbenchmark, diff --git a/NEWS.md b/NEWS.md index 9121a17..0042bec 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,9 @@ +# Version 0.1.1 + + * Added the ability to push the generated documentation to the + [gh-pages](https://robertzk.github.io/rocco) branch of your repo. + When calling `rocco::rocco`, set `gh_pages = TRUE`. + # Version 0.1.0 - * The initial creation of the package. + * The initial creation of the package. diff --git a/R/rocco.R b/R/rocco.R index 5364d8f..e6b7389 100644 --- a/R/rocco.R +++ b/R/rocco.R @@ -10,6 +10,8 @@ #' immediately for browsing. This will be set to \code{\link{interactive()}}, #' that is, TRUE if the R session is running interactive and FALSE #' otherwise. +#' @param gh_pages logical. If set to true, rocco docs will be served on +#' your gh-pages branch. #' @export #' @return TRUE or FALSE according as the documentation process succeeds. # Additional side effects are the creation of the documentation in the @@ -24,7 +26,8 @@ #' # The below will simply create a static HTML site without opening it. #' rocco("/path/to/package", output_dir = "/my/html/dir", browse = FALSE) #' } -rocco <- function(directory, output_dir = tempdir(), browse = interactive()) { +rocco <- function(directory, output_dir = tempdir(), browse = interactive(), gh_pages = FALSE) { + if (missing(directory)) directory <- "." stopifnot(is.character(directory), length(directory) == 1, is.character(output_dir), length(output_dir) == 1, isTRUE(browse) || isFALSE(browse), @@ -32,17 +35,18 @@ rocco <- function(directory, output_dir = tempdir(), browse = interactive()) { tryCatch({ rocco_(directory, output_dir) + if (isTRUE(gh_pages)) { + `commit_to_gh_pages!`(directory, output_dir) + } if (browse) browseURL(file.path(output_dir, "index.html")) - - TRUE - }, error = function(.) FALSE) + invisible(TRUE) + }, error = function(.) invisible(FALSE)) } rocco_ <- function(directory, output) { - rocco_skeleton(output) + rocco_skeleton(output) template <- readLines(file.path(output, "index.html")) compile(directory, template, file.path(output, "index.html")) } - diff --git a/R/utils.R b/R/utils.R index 7516f7e..689f8ce 100644 --- a/R/utils.R +++ b/R/utils.R @@ -22,3 +22,33 @@ description_file_attribute <- function(pkg_path, attribute) { as.character(read.dcf(file.path(pkg_path, "DESCRIPTION"))[1, attribute]) } +`commit_to_gh_pages!` <- function(directory, dir) { + ## A little bit of git magic + + ## Now that we have the docs, we need to transfer them to the gh-pages + ## branch of the repo, commit and push. + ## Switch to gh-pages branch + cur_branch <- system('git rev-parse --abbrev-ref HEAD', intern = TRUE) + on.exit({ + system(paste('git checkout', cur_branch)) + }) + + st <- system2('git', 'checkout gh-pages') + if (st == 1) system2('git', 'checkout -b gh-pages') + + ## Copy the docs to the repo folder, and push them upstream + system(paste0('cp -rf ', dir, "/* ", directory)) + in_dir(directory, { + system('git add -A .') + system('git commit -m "Updated Rocco docs."') + system('git push origin gh-pages') + }) + invisible(TRUE) +} + +## Don't want to import devtools because of in_dir +in_dir <- function(new, code) { + old <- setwd(new) + on.exit(setwd(old)) + force(code) +} diff --git a/README.md b/README.md index 5d0db10..37daed8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -Literate Documentation for R Packages [![Build Status](https://travis-ci.org/robertzk/rocco.svg?branch=master)](https://travis-ci.org/robertzk/rocco) [![Coverage Status](https://coveralls.io/repos/robertzk/rocco/badge.svg?branch=master)](https://coveralls.io/r/robertzk/rocco) +Literate Documentation for R Packages [![Build Status](https://travis-ci.org/robertzk/rocco.svg?branch=master)](https://travis-ci.org/robertzk/rocco) [![Coverage Status](https://coveralls.io/repos/robertzk/rocco/badge.svg?branch=master)](https://coveralls.io/r/robertzk/rocco) [![Documentation](https://img.shields.io/badge/rocco--docs-%E2%9C%93-blue.svg)](http://robertzk.github.io/rocco/) -------------------- Literate documentation for R packages in the spirit of Coffeescript's [docco](https://github.com/jashkenas/docco) @@ -9,6 +9,9 @@ To document your package, simply run ```R rocco::rocco("/path/to/package") # Will open browser interactively. +# This will build the docs and push them to the repos gh-pages branch +rocco::rocco("/path/to/package", gh_pages = TRUE) + # This will install the rocco docs to /path/to/pkg/inst/docs/rocco rocco::rocco("/path/to/pkg", "/path/to/pkg/inst/docs/rocco", browse = FALSE) ``` @@ -35,4 +38,3 @@ Many thanks go to * [Sindre Sorhus](https://github.com/sindresorhus) for the [Github Markdown style](https://github.com/sindresorhus/github-markdown-css). * [Jeremy Ashkenas](https://github.com/jashkenas) for [the original](https://github.com/jashkenas/docco) inspiration. - diff --git a/man/rocco.Rd b/man/rocco.Rd index 84bd8c6..1a39256 100644 --- a/man/rocco.Rd +++ b/man/rocco.Rd @@ -6,7 +6,8 @@ \alias{rocco-package} \title{Literate Documentation For R.} \usage{ -rocco(directory, output_dir = tempdir(), browse = interactive()) +rocco(directory, output_dir = tempdir(), browse = interactive(), + gh_pages = FALSE) } \arguments{ \item{directory}{character. The package directory to document.} @@ -18,6 +19,9 @@ By default, an extemporaneously-generated temporary directory.} immediately for browsing. This will be set to \code{\link{interactive()}}, that is, TRUE if the R session is running interactive and FALSE otherwise.} + +\item{gh_pages}{logical. If set to true, rocco docs will be served on +your gh-pages branch.} } \value{ TRUE or FALSE according as the documentation process succeeds.