BiocBook is a package to facilitate the creation of package-based, versioned online books. Such books can be used in a variety of contexts, including extended technical documentation (e.g. of an ecosystem based on multiple packages) or online workshops.

BiocBook assists authors in:

  1. Writing: compile a body of biological and/or bioinformatics knowledge;
  2. Containerizing: provide Docker images (through GitHub) to reproduce the examples illustrated in the compendium;
  3. Publishing: let Bioconductor or Github deploy an online book to disseminate the compendium;
  4. Versioning: automatically generate specific online book versions and Docker images for specific Bioconductor releases.

1 Main features of BiocBooks

BiocBooks created with the {BiocBook} package and hosted on GitHub are deployed and served on the gh-pages branch and a Docker image is available on ghcr.io.

BiocBooks created with the {BiocBook} package and submitted to Bioconductor are directly available for reading from the Bioconductor website.

Read the BiocBookDemo example book to know more about BiocBooks features.

2 Creating a BiocBook

A new BiocBook should be created using the init(new_package = "...") function.

This function performs the following operations:

  1. It checks that the provided package name is available;
  2. It logs in the GitHub user accounts;
  3. It creates a new remote Github repository using the BiocBook.template from js2264/BiocBook;
  4. It sets up Github Pages to serve the future books from the gh-pages branch;
  5. It clones the remote Github repository to a local folder;
  6. It edits several placeholders from the template and commits the changes.
library(BiocBook)

## Note that `.local = TRUE` is only set here for demonstration. 
init("myNewBook", .local = TRUE)
#> ══ Running preflight checklist ═════════════════════════════════════════════════
#> ⠙ Checking that no folder named `myNewBook` already exists
#> ⠙ Checking package name availability
#> ✔ Package name `myNewBook` is available
#> ⠙ Checking package name availability
! Dummy git configured
#> ⠙ Checking package name availability
• git user: `dummy`
#> ⠙ Checking package name availability
• git email: `dummy@dummy.com`
#> ⠙ Checking package name availability
! No GitHub configured
#> ⠙ Checking package name availability
• github user: NULL
#> ⠙ Checking package name availability
• PAT: NULL
#> ⠙ Checking package name availability
#> ══ Initiating a new `BiocBook` ═════════════════════════════════════════════════
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
#> ✔ New local book `myNewBook` successfully created
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
✔ Filled out `inst/assets/_book.yml` fields
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
✔ Filled out `README.md` fields
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
✔ Filled out `DESCRIPTION` fields
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
ℹ Please finish editing the `DESCRIPTION` fields, including:
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
  • Title
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
  • Description
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
  • Authors@R
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
✔ Filled out `inst/index.qmd` fields
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
ℹ Please finish editing the `inst/index.qmd` fields, including the `Welcome` section
#> ⠙ Creating new repository from template provided in BiocBook `inst/` directory`
ℹ The following files need to be committed: 
#>   • .Rbuildignore
#>   • .github/
#>   • DESCRIPTION
#>   • Dockerfile
#>   • LICENSE
#>   • LICENSE.md
#>   • NAMESPACE
#>   • README.md
#>   • inst/
#>   • vignettes/
#> ✔ The new files have been commited to the `devel` branch.
#> ── NOTES ───────────────────────────────────────────────────────────────────────
#> ℹ If you wish to change the cover picture, please replace the following file:
#> • inst/assets/cover.png
#> ══ Results ═════════════════════════════════════════════════════════════════════
#> ✔ Local `BiocBook` directory successfully created  : myNewBook
#> ! This book will be only available in local until a Github remote is set.
#> 
#> # You can connect to the local directory as follows:
#>   biocbook <- BiocBook('myNewBook')

3 The BiocBook class

A BiocBook object acts as a pointer to a local package directory, with book chapters contained in a pages/ folder as .qmd files.

bb <- BiocBook("myNewBook")
bb
#> BiocBook object
#> - local path: /tmp/RtmpO3qKxF/Rbuild6a3cc1c66b4b9/BiocBook/vignettes/myNewBook
#> - remote url:
#> - Title: myNewBook
#> - Releases(0):
#> - Chapters(1):
#>   • Welcome [/inst/index.qmd]

4 Editing an existing BiocBook

BiocBook objects can be modified using the following helper functions:

  • add_preamble(biocbook) to start writing a preamble;
  • add_chapter(biocbook, title = "...") to start writing a new chapter;
  • edit_page(biocbook, page = "...") to edit an existing chapter.
add_preamble(bb, open = FALSE)
#> ✔ File created @ `/tmp/RtmpO3qKxF/Rbuild6a3cc1c66b4b9/BiocBook/vignettes/myNewBook/inst/pages/preamble.qmd`
add_chapter(bb, title = 'Chapter 1', open = FALSE)
#> ✔ File created @ `/tmp/RtmpO3qKxF/Rbuild6a3cc1c66b4b9/BiocBook/vignettes/myNewBook/inst/pages/chapter-1.qmd`
bb
#> BiocBook object
#> - local path: /tmp/RtmpO3qKxF/Rbuild6a3cc1c66b4b9/BiocBook/vignettes/myNewBook
#> - remote url:
#> - Title: myNewBook
#> - Releases(0):
#> - Chapters(3):
#>   • Welcome [/inst/index.qmd]
#>   • Preamble [/inst/pages/preamble.qmd]
#>   • Chapter 1 [/inst/pages/chapter-1.qmd]
  • preview(biocbook) will compile (and cache) the book locally. Use it to verify that your book renders correctly.

5 Publishing an existing BiocBook

As long as the local BiocBook has been initiated with init(), the writer simply has to commit changes and push them to the origin remote.

In R, this can be done as follows:

publish(bb)

The different available versions published in the origin gh-pages branch can be listed using status(biocbook).

6 Session info

sessionInfo()
#> R Under development (unstable) (2024-10-21 r87258)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.1 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.21-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_GB              LC_COLLATE=C              
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] BiocBook_1.5.0   BiocStyle_2.35.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] janeaustenr_1.0.0   sass_0.4.9          generics_0.1.3     
#>  [4] renv_1.0.11         lattice_0.22-6      stringi_1.8.4      
#>  [7] digest_0.6.37       magrittr_2.0.3      grid_4.5.0         
#> [10] evaluate_1.0.1      bookdown_0.41       fastmap_1.2.0      
#> [13] rprojroot_2.0.4     jsonlite_1.8.9      Matrix_1.7-1       
#> [16] tidytext_0.4.2      BiocManager_1.30.25 httr_1.4.7         
#> [19] purrr_1.0.2         stringdist_0.9.14   available_1.1.0    
#> [22] jquerylib_0.1.4     cli_3.6.3           rlang_1.1.4        
#> [25] tokenizers_0.3.0    gitcreds_0.1.2      withr_3.0.2        
#> [28] cachem_1.1.0        yaml_2.3.10         tools_4.5.0        
#> [31] parallel_4.5.0      memoise_2.0.1       dplyr_1.1.4        
#> [34] BiocGenerics_0.53.3 credentials_2.0.2   vctrs_0.6.5        
#> [37] R6_2.5.1            lifecycle_1.0.4     stringr_1.5.1      
#> [40] fs_1.6.5            usethis_3.1.0       pkgconfig_2.0.3    
#> [43] desc_1.4.3          pillar_1.10.0       bslib_0.8.0        
#> [46] Rcpp_1.0.13-1       glue_1.8.0          gh_1.4.1           
#> [49] gert_2.1.4          xfun_0.49           tibble_3.2.1       
#> [52] tidyselect_1.2.1    sys_3.4.3           knitr_1.49         
#> [55] SnowballC_0.7.1     htmltools_0.5.8.1   rmarkdown_2.29     
#> [58] compiler_4.5.0      askpass_1.2.1       openssl_2.3.0