diff --git a/README.md b/README.md index 9cadfe1..4dd378b 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,70 @@ -# `template-workshop`: A template for creating Quarto-based workshops - -[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json)](https://github.com/copier-org/copier) -[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/rostools/tempate-workshop/main.svg)](https://results.pre-commit.ci/latest/github/rostools/template-workshop/main) -[![GitHub Release](https://img.shields.io/github/v/release/rostools/template-workshop)](https://github.com/rostools/template-workshop/releases/latest) - - -Release -Zenodo DOI - -## Features - -- Uses [Quarto](https://quarto.org/) for the workshop content, allowing for easy - integration of code, text, and figures. -- Includes a [justfile](https://just.systems/man/en/) for managing common tasks - like building the workshop and running checks. -- Uses [typos](https://github.com/crate-ci/typos) to check for common - spelling mistakes. -- For R projects, uses [Air](https://posit-dev.github.io/air/) to format and check - R code. -- Uses [Commitizen](https://commitizen-tools.github.io/commitizen/) to check - commit messages, create the changelog, tag the repository, and create a - a GitHub release. -- Uses a [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) license. -- Run checks with with [pre-commit](https://pre-commit.com/) hooks to ensure - consistent formatting and style across the project. It includes checks for - credentials, typos, and file formatting. -- Uses [rostools-theme]() Quarto extension for a standard appearance across - workshops. -- Includes [GitHub Actions](https://docs.github.com/en/actions) for continuous - integration and delivery for running checks, formatting, releasing, and building - the website. -- Uses [Netlify](https://www.netlify.com/) for hosting the workshop website, - which is automatically built and deployed with Quarto's GitHub Action workflow. -- Includes an [EditorConfig](https://editorconfig.org/) file to ensure consistent - formatting across different editors. -- Sets some common VS Code settings for the project, including suggesting - extensions - - -## Using - -This template uses [Copier](https://copier.readthedocs.io/) to create a folder -with relevant files for a rostools-structured workshop. We use -[uv](https://docs.astral.sh/uv) to run the commands, so you'll need to install -that first. After that, creating a new workshop project folder can be done with: - -```bash -uvx copier copy gh:rostools/template-workshop WORKSHOP-NAME -``` - -Where `WORKSHOP-NAME` is the name of the folder you want to create. This will -copy the template files into that folder, and you can then edit them as needed. -When you use it, it will ask you a series of questions to correctly set up the -workshop folder. + + +# Template Workshop: An opinionated setup for making workshops as open educational resources + + + +[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true)](https://github.com/copier-org/copier) +[![GitHub +License](https://img.shields.io/github/license/rostools/template-workshop)](https://github.com/rostools/template-workshop/blob/main/LICENSE.md) +[![GitHub +Release](https://img.shields.io/github/v/release/rostools/template-workshop)](https://github.com/rostools/template-workshop/releases/latest) +[![Test](https://github.com/rostools/template-workshop/actions/workflows/test.yml/badge.svg)](https://github.com/rostools/template-workshop/actions/workflows/test.yml) +[![Build +website](https://github.com/rostools/template-workshop/actions/workflows/build-website.yml/badge.svg)](https://github.com/rostools/template-workshop/actions/workflows/build-website.yml) +[![pre-commit.ci +status](https://results.pre-commit.ci/badge/github/rostools/template-workshop/main.svg)](https://results.pre-commit.ci/latest/github/rostools/template-workshop/main) +[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Project Status: Active – The project has reached a stable, usable +state and is being actively +developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) + +This repository contains a template for setting up a new workshop +repository that will contain files to create a website for a workshop +and that might also be used as an open educational resource (OER). Use +this template to quickly get started with a new workshop with all the +necessary files and configurations in place for a smoother “developer +experience” and to have [continuous +delivery/deployment](https://en.wikipedia.org/wiki/Continuous_delivery) +of the workshop website and archival to Zenodo. + +Check out our [website](https://template-workshop.rostools.org/) for +more information, such as the features it provides, a +[guide](https://template-workshop.rostools.org/docs/guide/) for using +the template. For a list of changes, see our +[changelog](https://template-workshop.rostools.org/docs/releases/) page. + +## Contributing + +Check out our [contributing +page](https://template-workshop.rostools.org/contributing/) for +information on how to contribute to the project, including how to set up +your development environment. + +Please note that this project is released with a [Contributor Code of +Conduct](https://github.com/rostools/template-workshop/blob/main/CODE_OF_CONDUCT.md). +By participating in this project you agree to abide by its terms. + +## Licensing + +This project is licensed under the [MIT +License](https://github.com/rostools/template-workshop/blob/main/LICENSE.md). + +## Citing + +This project is part of rostools, which is an organisation that hosts +and runs workshops (also as open educational resources) that are related +in some way to doing reproducible and open science. If you use this +project in your work, please cite it as follows: + +Johnston L.W., Brødbæk S.K. Template Workshop: An opinionated setup for +making workshops as open educational resources URL: +https://template-workshop.rostools.org + +Or as a BibTeX entry: + + @misc{YourReferenceHere, + author = {Johnston, Luke William and Brødbæk, Signe Kirk}, + title = {Template Workshop: An opinionated setup for making workshops as open educational resources}, + url = {https://template-workshop.rostools.org} + } diff --git a/README.qmd b/README.qmd new file mode 100644 index 0000000..43ffd9c --- /dev/null +++ b/README.qmd @@ -0,0 +1,63 @@ +--- +format: gfm +execute: + echo: false +jupyter: python3 +metadata-files: + - _quarto.yml +--- + +# Template Workshop: An opinionated setup for making workshops as open educational resources + +{{< include /docs/includes/_badges.qmd >}} + +This repository contains a template for setting up a new workshop +repository that will contain files to create a website for a workshop +and that might also be used as an open educational resource (OER). +Use this template to quickly get started with a new workshop with all +the necessary files and configurations in place for a smoother +"developer experience" and to have [continuous +delivery/deployment](https://en.wikipedia.org/wiki/Continuous_delivery) +of the workshop website and archival to Zenodo. + +Check out our +[website](https://{{< meta gh.repo >}}.{{< meta gh.org >}}.org/) for more +information, such as the features it provides, a +[guide](https://{{< meta gh.repo >}}.{{< meta gh.org >}}.org/docs/guide/) +for using the template. For a list of changes, see our +[changelog](https://{{< meta gh.repo >}}.{{< meta gh.org >}}.org/docs/releases/) +page. + +## Contributing + +Check out our [contributing +page](https://{{< meta gh.repo >}}.{{< meta gh.org >}}.org/contributing/) +for information on how to contribute to the project, including how to +set up your development environment. + +Please note that this project is released with a [Contributor Code of +Conduct](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/CODE_OF_CONDUCT.md). +By participating in this project you agree to abide by its terms. + +## Licensing + +This project is licensed under the [MIT +License](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md). + +## Citing + +This project is part of rostools, which is an organisation that hosts +and runs workshops (also as open educational resources) that are related +in some way to doing reproducible and open science. If you use this +project in your work, please cite it as follows: + +```{python} +#| output: asis +!uvx --quiet cffconvert --format apalike +``` + +Or as a BibTeX entry: + +```{python} +!uvx --quiet cffconvert --format bibtex +``` diff --git a/docs/includes/_badges.qmd b/docs/includes/_badges.qmd new file mode 100644 index 0000000..5b4998f --- /dev/null +++ b/docs/includes/_badges.qmd @@ -0,0 +1,9 @@ + +[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true)](https://github.com/copier-org/copier) +[![GitHub License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}})](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md) +[![GitHub Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}})](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest) +[![Test](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/test.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/test.yml) +[![Build website](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main) +[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)