BiocDeployable Template for Quarto documents

This is a BiocDeployable template repository, notably for rendering and deploying Quarto documents.

Getting Started

0. Background info

Source QMD files

In the vignettes/ directory, you will find the source Quarto Markdown (.qmd) files, representing the material to be rendered and deployed.

By default, this repository will have an example file containing both R and Python code. You can start by renaming and editing the example file. You can add as many qmd files as you want in the vignettes/ directory, all of which will render all output formats in the autogenerated/quarto directory, as well as build Docker images with installed dependencies and rendered documents.

Dependencies

Some dependencies do not have to explicitly defined, and will be scraped at runtime by a script in the GitHub Action, including: - R packages hosted by CRAN (eg: install.packages("packagename")) - R packages hosted by Bioconductor (eg: BiocManager::install("packagename")) - Python modules hosted by PyPi (eg: pip install packagename)

TODO: Additional dependencies declaration

Outputs

The GitHub actions listed in the table above will generate two kinds of outputs: - Documents rendered by Quarto from the source QMD files, which will be pushed by the action in the autogenerated/quarto directory within your GitHub repository. - Docker images which will be pushed to the GitHub Container Registry with the name of your GitHub repository.

1. Forking the repository

You can get started by creating your own repository from this template.

Choose an all lowercase shortname for the repository, and write a brief description which will serve as your document title. You can rename your repository at a later time in the GitHub settings.

When you fork the repository, an automatic GitHub Action will be dispatched and edit your README.md, pointing links to your own repository. You can freely edit this README file yourself after this initial push.

2. Adding your Quarto Markdown documents

The next step is to add your Quarto Markdown documents. The below walkthrough will show you how to edit documents in the browser. If you are familiar with git, you can make your changes locally and push as usual.

Editing example document

This repository comes with an example document to help get you started. You can edit this document in your browser by clicking on the pencil as shown below:

Note that you can also rename the file by editing the text shown below. Remember however to keep the .qmd extension which is used by the scripts.

After making your changes, you can add a descriptive message then commit them back to the repository.

After each change is made to your repository, a new GitHub action is dispatched to try rendering your document, then generating deployable Docker images for your repository. These artifacts will be updated with each change. The table below details the GitHub actions and their outputs.

Adding Quarto documents

Beyond the example document, which you can also delete, you can add as many Quarto documents as you like to each repository, for example a document per educational module. These documents need to be added in the vignettes/ directory, and can be done so in the browser by clicking the "Add File" button shown below.

GitHub Actions

This repository notably includes the following GitHub actions:

| Description | Job Source | Outputs | Trigger | |--------------------------------------------------------------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------|---------------------| | Installing dependencies and Rendering Quarto documents | quarto_rendering.yaml | autogenerated/quarto directory | Every pushed commit | | Building Bioconductor RStudio Docker image | docker_build.yaml#buildrstudio | ghcr.io/almahmoud/biocdeployablequarto:biocrstudio-main docker image | Every pushed commit | | Building Jupyter Docker image for deployment in Galaxy | docker_build.yaml#buildgxyjupyter | ghcr.io/almahmoud/biocdeployablequarto:gxyjupyter-main docker image | Every pushed commit | | Building Bioconductor RStudio Docker image for deployment on AnVIL | docker_build.yaml#buildanvilrstudio | ghcr.io/almahmoud/biocdeployablequarto:biocanvil-main docker image | Every pushed commit |