---
title: "BiocBook: write Quarto books with Bioconductor"
output: 
  BiocStyle::html_document:
    self_contained: yes
    toc: true
    toc_float: true
    toc_depth: 2
    code_folding: show
date: "`r doc_date()`"
package: "`r pkg_ver('BiocBook')`"
vignette: >
  %\VignetteIndexEntry{BiocBook}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    crop = NULL ## Related to https://stat.ethz.ch/pipermail/bioc-devel/2020-April/016656.html
)
```

`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](https://contributions.bioconductor.org/use-devel.html). 

# 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](https://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`](http://jserizay.com/BiocBookDemo/devel/#main-features-of-biocbooks)
example book to know more about `BiocBook`s features. 

# 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. 

```{r}
library(BiocBook)

## Note that `.local = TRUE` is only set here for demonstration. 
init("myNewBook", .local = TRUE)
```

# 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.  

```{r}
bb <- BiocBook("myNewBook")
bb
```

# 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.

```{r}
add_preamble(bb, open = FALSE)
add_chapter(bb, title = 'Chapter 1', open = FALSE)
bb
```

- `preview(biocbook)` will compile (and cache) the book locally. Use it 
to verify that your book renders correctly. 

# 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: 

```{r eval = FALSE}
publish(bb)
```

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

# Session info 

```{r}
sessionInfo()
```

```{r, include = FALSE}
unlink("myNewBook", recursive = TRUE)
```