Skip to content

Latest commit

 

History

History
94 lines (61 loc) · 5.71 KB

README.md

File metadata and controls

94 lines (61 loc) · 5.71 KB

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:

1. Forking the repository

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

use-template-button

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.

choose-names

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: pencil-to-edit

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.

renaming

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

committing

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.

add-file

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