This is a BiocDeployable template repository, notably for rendering and deploying Quarto documents.
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.
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)
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/quartodirectory within your GitHub repository. - Docker images which will be pushed to the GitHub Container Registry with the name of your GitHub 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.
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.
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.
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.
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 |