compileBook: Compile the book

In LTLA/rebook: Re-using Content in Bioconductor Books

Compile the book

Description

Copy a bookdown book to a separate workspace prior to compilation, and then copy the compiled book to a final location.

Usage

preCompileBook(src.dir, work.dir, desc = NULL)

postCompileBook(work.dir, final.dir, handle = NULL)

Arguments

src.dir	String containing the path to the book Rmarkdown sources.
work.dir	String containing the path to the versioned cache directory used to compile the book, see the dir.expiry package for details.
desc	String containing the path to a DESCRIPTION file to copy into work.dir. Typically used when the book is to inherit the DESCRIPTION of the enclosing package.
final.dir	String containing the path to the final location for the compiled book's HTMLs.
handle	The lock handle returned by preCompileBook.

Details

These two functions should bracket a render_book call. We do not make these into a single function as calling render_book inside another function inside a package does not interact properly with some imports. The offending example is that of cbind, which fails to be converted into an S4 generic (this would normally happen when BiocGenerics gets attached).

preCompileBook may take some time as it will compile all chapters via compileChapter. It does so by locking and unlocking each chapter as it is compiled, thus avoiding problems with concurrent attempts to compile the same chapter via extractFromPackage. (Concurrent compilation of different chapters is still supported and allows for parallel package builds.) The actual compilation of the book with bookdown will simply re-use these caches for efficiency.

After compilation of the individual chapters, preCompileBook will lock the entire work.dir. This ensures that bookdown's directory shuffling does not break concurrent processes using the knitr cache directories. The lock can be released by passing the returned handle to handle in postCompileBook.

Value

For preCompileBook, work is populated with the book sources and intermediate content (e.g., caches). A lock handle is returned.

For postCompileBook, final is populated with the HTMLs. Cache directories are moved out of _bookdown_files into their original location.

In both cases, a NULL is invisibly returned.

Author(s)

Aaron Lun

See Also

configureBook, where this function is called in the Makefile.

bookCache, the default choice for work.dir.

LTLA/rebook documentation built on June 5, 2023, 6:24 p.m.