# BiocBook: write Quarto books with Bioconductor

#### 24 October 2023

#### Package

BiocBook 1.0.0

`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 `BiocBook`s

`BiocBook`s 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.

`BiocBook`s 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 `BiocBook`s 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`
    #> Warning in readLines(file): incomplete final line found on
    #> 'myNewBook/DESCRIPTION'
    #> ✔ 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/RtmpF6kSma/Rbuildaff914766de95/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/RtmpF6kSma/Rbuildaff914766de95/BiocBook/vignettes/myNewBook/inst/pages/preamble.qmd`
    add_chapter(bb, title = 'Chapter 1', open = FALSE)
    #> ✔ File created @ `/tmp/RtmpF6kSma/Rbuildaff914766de95/BiocBook/vignettes/myNewBook/inst/pages/chapter-1.qmd`
    bb
    #> BiocBook object
    #> - local path: /tmp/RtmpF6kSma/Rbuildaff914766de95/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 version 4.3.1 (2023-06-16)
    #> Platform: x86_64-pc-linux-gnu (64-bit)
    #> Running under: Ubuntu 22.04.3 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /home/biocbuild/bbs-3.18-bioc/R/lib/libRblas.so
    #> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.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.0.0   BiocStyle_2.30.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] janeaustenr_1.0.0   sass_0.4.7          utf8_1.2.4
    #>  [4] generics_0.1.3      renv_1.0.3          lattice_0.22-5
    #>  [7] stringi_1.7.12      digest_0.6.33       magrittr_2.0.3
    #> [10] grid_4.3.1          evaluate_0.22       bookdown_0.36
    #> [13] fastmap_1.1.1       Matrix_1.6-1.1      rprojroot_2.0.3
    #> [16] jsonlite_1.8.7      tidytext_0.4.1      BiocManager_1.30.22
    #> [19] httr_1.4.7          purrr_1.0.2         fansi_1.0.5
    #> [22] stringdist_0.9.10   available_1.1.0     jquerylib_0.1.4
    #> [25] cli_3.6.1           rlang_1.1.1         tokenizers_0.3.0
    #> [28] gitcreds_0.1.2      withr_2.5.1         cachem_1.0.8
    #> [31] yaml_2.3.7          tools_4.3.1         parallel_4.3.1
    #> [34] memoise_2.0.1       dplyr_1.1.3         BiocGenerics_0.48.0
    #> [37] credentials_2.0.1   vctrs_0.6.4         R6_2.5.1
    #> [40] lifecycle_1.0.3     stringr_1.5.0       fs_1.6.3
    #> [43] usethis_2.2.2       desc_1.4.2          pkgconfig_2.0.3
    #> [46] pillar_1.9.0        bslib_0.5.1         Rcpp_1.0.11
    #> [49] glue_1.6.2          gh_1.4.0            gert_2.0.0
    #> [52] xfun_0.40           tibble_3.2.1        tidyselect_1.2.0
    #> [55] sys_3.4.2           knitr_1.44          SnowballC_0.7.1
    #> [58] htmltools_0.5.6.1   rmarkdown_2.25      compiler_4.3.1
    #> [61] askpass_1.2.0       openssl_2.1.1