diff --git a/NAMESPACE b/NAMESPACE index ec8aa7b..b218445 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -13,6 +13,7 @@ export(edit_yml) export(init) export(preview) export(publish) +export(quick_init) export(releases) export(status) exportClasses(BiocBook) diff --git a/R/doc.R b/R/doc.R index 7d5e70b..903c1a2 100644 --- a/R/doc.R +++ b/R/doc.R @@ -74,7 +74,8 @@ NULL #' `BiocBook`s are local R packages containing an extra `pages` folder to #' write up online book chapters. #' -#' 1. A new `BiocBook` should be created using `init(new_package = "...")`. +#' 1. A new `BiocBook` should be created using `init(new_package = "...")` (or +#' alternatively, locally with `quick_init(new_package = "...", user = "...")`). #' 2. A newly created `BiocBook` can be accessed to in R using `biocbook <- BiocBook(path = "...")`. #' 3. To edit an existing `BiocBook` object, several helper functions exist: #' - `add_preamble(biocbook)` @@ -112,6 +113,37 @@ NULL #' #' The `init(new_package = "...")` function returns a `BiocBook` object. #' +#' @section Quickly create a local `BiocBook`: +#' +#' Alternatively, a **local** `BiocBook` can be quickly created using the +#' `quick_init(new_package = "...", user = "...")` function. +#' +#' This function only creates a new **local** repository, using the +#' `BiocBook` template from `js2264/BiocBook`. +#' +#' It does **NOT**: +#' +#' - Check that the provided package name is available; +#' - Set up/push the local repository to a **remote** Github repository; +#' - Set up a `gh-pages` to serve rendered books; +#' +#' This implies that functions committing/pushing (`publish()`) +#' or checking remote status (`status()`) do not work properly with a +#' `BiocBook` initiated with `quick_init()`, unless a remote is manually +#' set up. +#' +#' To enable Github support for a local `BiocBook`, one has to manually +#' initiate a `git` repository and add a remote as follows: +#' +#' ```{sh eval = FALSE} +#' git init +#' git symbolic-ref HEAD refs/heads/devel +#' git add . +#' git commit -m 'first commit' +#' git remote add origin git@github.com:/.git +#' git push --set-upstream origin devel +#' ``` +#' #' @section Editing an existing `BiocBook`: #' #' `BiocBook` objects can be modified using the following helper functions: @@ -156,6 +188,7 @@ NULL #' @param new_package Name to use when initiating a new `BiocBook`. #' This name should be compatible with package naming conventions #' from R and Bioconductor (i.e. no `_` or `-`, no name starting with a number). +#' @param user Ideally, the Github ID of the main author/organization. #' @param push Optional. Logical, whether to automatically push commits to #' remote Github origin. If NA, a prompt will ask whether to push commits or #' not (default: NA). diff --git a/R/init.R b/R/init.R index cfe5e32..948756c 100644 --- a/R/init.R +++ b/R/init.R @@ -33,6 +33,14 @@ init <- function( } +#' @rdname BiocBook +#' @export + +quick_init <- function(new_package, user) { + .init_folder(new_package, user) + invisible(BiocBook(new_package)) +} + .preflight_checks <- function(new_package, skip_availability = FALSE, .local = FALSE) { cli::cat_rule("Running preflight checklist", col = "cyan", line = 2) diff --git a/man/BiocBook.Rd b/man/BiocBook.Rd index d158cd8..2d8abee 100644 --- a/man/BiocBook.Rd +++ b/man/BiocBook.Rd @@ -5,6 +5,7 @@ \name{BiocBook} \alias{BiocBook} \alias{init} +\alias{quick_init} \alias{BiocBook-class} \alias{releases} \alias{chapters} @@ -16,6 +17,8 @@ \usage{ init(new_package, push = NA, skip_availability = FALSE, .local = FALSE) +quick_init(new_package, user) + BiocBook(path) releases(object) @@ -45,6 +48,8 @@ not (default: NA).} \item{.local}{Should only be used for examples/tests. Whether to create a matching Github repository or stay local (default: FALSE).} +\item{user}{Ideally, the Github ID of the main author/organization.} + \item{path}{Path of an existing \code{BiocBook}.} \item{object}{A \code{BiocBook} object, created by \code{BiocBook} or \code{init()}.} @@ -62,7 +67,8 @@ information related to the \code{bb} BiocBook. \code{BiocBook}s are local R packages containing an extra \code{pages} folder to write up online book chapters. \enumerate{ -\item A new \code{BiocBook} should be created using \code{init(new_package = "...")}. +\item A new \code{BiocBook} should be created using \code{init(new_package = "...")} (or +alternatively, locally with \code{quick_init(new_package = "...", user = "...")}). \item A newly created \code{BiocBook} can be accessed to in R using \code{biocbook <- BiocBook(path = "...")}. \item To edit an existing \code{BiocBook} object, several helper functions exist: } @@ -109,6 +115,39 @@ This function performs the following operations: The \code{init(new_package = "...")} function returns a \code{BiocBook} object. } +\section{Quickly create a local \code{BiocBook}}{ + + +Alternatively, a \strong{local} \code{BiocBook} can be quickly created using the +\code{quick_init(new_package = "...", user = "...")} function. + +This function only creates a new \strong{local} repository, using the +\code{BiocBook} template from \code{js2264/BiocBook}. + +It does \strong{NOT}: +\itemize{ +\item Check that the provided package name is available; +\item Set up/push the local repository to a \strong{remote} Github repository; +\item Set up a \code{gh-pages} to serve rendered books; +} + +This implies that functions committing/pushing (\code{publish()}) +or checking remote status (\code{status()}) do not work properly with a +\code{BiocBook} initiated with \code{quick_init()}, unless a remote is manually +set up. + +To enable Github support for a local \code{BiocBook}, one has to manually +initiate a \code{git} repository and add a remote as follows: + +\if{html}{\out{
}}\preformatted{git init +git symbolic-ref HEAD refs/heads/devel +git add . +git commit -m 'first commit' +git remote add origin git@github.com:/.git +git push --set-upstream origin devel +}\if{html}{\out{
}} +} + \section{Editing an existing \code{BiocBook}}{