A BiocBook online book (a.k.a website): hosted on the repository gh-pages branch;
Both are built against the specific Bioconductor release X.Y.
What is this {BiocBook} package?
The {BiocBook} package offers a streamlined approach to creating BiocBooks, with several important benefits:
The author creates a {BiocBook}-based package without leaving R;
The author writes book chapters in pages/*.qmd files using enhanced markdown;
The author can submit its {BiocBook}-based package to Bioconductor.
The containerization and publishing of the new {BiocBook}-based package is automated:
Github Action workflow generates different Docker images for different Bioconductor releases, with the packages used in the book pre-installed;
A Github Action workflow publishes different book versions for different Bioconductor releases.
Main features of BiocBooks
Fully compatible with the Bioconductor Build System
When a {BiocBook}-based package is accepted into Bioconductor, it is automatically integrated into the Bionconductor Build System (BBS).
This means that it is getting built using R CMD build --keep-empty-dirs --no-resave-data .. This triggers the rendering of the book contained in /inst/. Book packages built by the BBS are then automatically deployed and are eventually available at https://bioconductor.org/books/<bioc_version>/<pkg>/.
Automated versioning of Docker images
A separate Docker image is built for each branch (named devel or RELEASE_X_Y) of a {BiocBook}-based Github repository.
Each Docker image provides pre-installed R packages:
Bioconductor release X.Y;
Specific book dependencies from Bioconductor release X.Y (listed in DESCRIPTION);
The book package itself
The Docker images also include a micromamba-based environment, named BiocBook, in which all the softwares listed in requirements.yml are installed.
For example, Docker images built from the {BiocBookDemo} package repository are available here:
You can get access to all the packages used in this book in < 1 minute, using this command in a terminal:
docker run -it ghcr.io/js2264/biocbookdemo:devel R
Automated versioning of the online book
Regardless of whether the book package is submitted to Bioconductor, a Github Actions workflow publishes individual online books for each branch (named devel or RELEASE_X_Y) of a BiocBook-based Github repository.
For example, the online book version matching the devel version of the {BiocBook} package is available from:
An RStudio Server instance based on a specific Bioconductor <version> (devel or RELEASE_X_Y) can be initiated from the corresponding Docker image as follows:
docker run \--volume<local_folder>:<destination_folder>\-e PASSWORD=OHCA \-p 8787:8787 \ ghcr.io/<github_user>/<biocbook_repo>:<version>
Further instructions regarding Bioconductor-based Docker images are available here.
Acknowledgments
This works was inspired by and closely follows the strategy used in coordination by the Bioconductor core team and Aaron Lun to submit book-containing packages (from the OSCA series as well as SingleR and csaw books).
Orchestrating Single-Cell Analysis with Bioconductor (n.d.)
Xie, Yihui. 2014. βKnitr: A Comprehensive Tool for Reproducible Research in R.β In Implementing Reproducible Computational Research, edited by Victoria Stodden, Friedrich Leisch, and Roger D. Peng. Chapman; Hall/CRC.
βββ. 2016. Bookdown: Authoring Books and Technical Documents with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/bookdown.