From 72290ff0844a0da27b8c158d19cac7359d5d860a Mon Sep 17 00:00:00 2001 From: dagousket Date: Mon, 9 Dec 2024 10:52:59 +0000 Subject: [PATCH 1/4] doc: add code of conduct --- .Rbuildignore | 1 + CODE_OF_CONDUCT.md | 126 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/.Rbuildignore b/.Rbuildignore index e847696..96dae84 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -11,3 +11,4 @@ ^\.github$ ^docs$ ^pkgdown$ +^CODE_OF_CONDUCT\.md$ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..948901e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,126 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to one or more of the project maintainers.. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion]. + +For answers to common questions about this code of conduct, see the FAQ at +. Translations are available at . + +[homepage]: https://www.contributor-covenant.org From 5d7270f60ced1d2774c6f5cbfb54294e7656fb7a Mon Sep 17 00:00:00 2001 From: dagousket Date: Mon, 9 Dec 2024 10:53:15 +0000 Subject: [PATCH 2/4] doc: add package level doc --- DESCRIPTION | 3 ++- R/squash-package.R | 6 ++++++ man/squash-package.Rd | 31 +++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 R/squash-package.R create mode 100644 man/squash-package.Rd diff --git a/DESCRIPTION b/DESCRIPTION index 9b41f93..c3cd2e4 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -9,7 +9,8 @@ Authors@R: c( Description: Compile n .qmd (under format revealjs) to one single html file. License: MIT + file LICENSE -URL: https://thinkr-open.github.io/squash/, https://github.com/ThinkR-open/squash +URL: https://thinkr-open.github.io/squash/, + https://github.com/ThinkR-open/squash Imports: cli, dplyr, diff --git a/R/squash-package.R b/R/squash-package.R new file mode 100644 index 0000000..a65cf64 --- /dev/null +++ b/R/squash-package.R @@ -0,0 +1,6 @@ +#' @keywords internal +"_PACKAGE" + +## usethis namespace: start +## usethis namespace: end +NULL diff --git a/man/squash-package.Rd b/man/squash-package.Rd new file mode 100644 index 0000000..42f079e --- /dev/null +++ b/man/squash-package.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/squash-package.R +\docType{package} +\name{squash-package} +\alias{squash} +\alias{squash-package} +\title{squash: Several Quarto As Single HTML} +\description{ +\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} + +Compile n .qmd (under format revealjs) to one single html file. +} +\seealso{ +Useful links: +\itemize{ + \item \url{https://thinkr-open.github.io/squash/} + \item \url{https://github.com/ThinkR-open/squash} +} + +} +\author{ +\strong{Maintainer}: Antoine Languillaume \email{antoine@thinkr.fr} + +Authors: +\itemize{ + \item Colin Fay \email{colin@thinkr.fr} + \item Swann Floc'hlay \email{swann@thinkr.fr} +} + +} +\keyword{internal} From 2f1569388ee8d6a3f719d5a87fee506b945eb386 Mon Sep 17 00:00:00 2001 From: dagousket Date: Mon, 9 Dec 2024 10:53:30 +0000 Subject: [PATCH 3/4] doc: update readme --- README.Rmd | 26 ++++++++++++++++++-------- README.md | 33 ++++++++++++++++++++++++++------- 2 files changed, 44 insertions(+), 15 deletions(-) diff --git a/README.Rmd b/README.Rmd index 29e6ea6..53c417b 100644 --- a/README.Rmd +++ b/README.Rmd @@ -17,27 +17,32 @@ knitr::opts_chunk$set( [![Codecov test coverage](https://codecov.io/gh/ThinkR-open/squash/graph/badge.svg)](https://app.codecov.io/gh/ThinkR-open/squash) -The goal of {squash} is to compile n .qmd presentations to one single html file. +The goal of {squash} is to compile a single html presentation file from multiple independent quarto files. -The main purpose of this is to create custom slide decks from several -chapter .qmd files. +The main purpose of this is to create custom slide decks from several chapter quarto files. The resulting html file can be themed via quarto extensions. ## Installation +You can install the **stable** version from [GitHub](https://github.com/Thinkr-open/squash) with: + ```{r eval=FALSE} +remotes::install_github("Thinkr-open/squash", ref = "production") +``` -``` +You can install the **development** version from [GitHub](https://github.com/Thinkr-open/squash) with: -## External dependencies +```{r eval=FALSE} +remotes::install_github("Thinkr-open/squash", ref = "main") +``` -This package relies on quarto > 1.3. +This package relies on quarto > 1.3 (see its [download page](https://quarto.org/docs/download/)). -Link to quarto: [download page](https://quarto.org/docs/download/) +## Play with `{squash}` -## How to use it +### Simple case ```{r} library(squash) @@ -106,6 +111,11 @@ unlink(temp_dir, recursive = TRUE) unlink(tmp_course_path, recursive = TRUE) ``` +## Code of Conduct + +Please note that this project is released with a [Contributor Code of Conduct](https://www.contributor-covenant.org/version/1/0/0/code-of-conduct.html). +By participating in this project you agree to abide by its terms. + ## Devs ### Check diff --git a/README.md b/README.md index 99c2ad3..13b2b14 100644 --- a/README.md +++ b/README.md @@ -10,23 +10,36 @@ coverage](https://codecov.io/gh/ThinkR-open/squash/graph/badge.svg)](https://app.codecov.io/gh/ThinkR-open/squash) -The goal of {squash} is to compile n .qmd presentations to one single -html file. +The goal of {squash} is to compile a single html presentation file from +multiple independent quarto files. The main purpose of this is to create custom slide decks from several -chapter .qmd files. +chapter quarto files. The resulting html file can be themed via quarto extensions. ## Installation -## External dependencies +You can install the **stable** version from +[GitHub](https://github.com/Thinkr-open/squash) with: -This package relies on quarto \> 1.3. +``` r +remotes::install_github("Thinkr-open/squash", ref = "production") +``` + +You can install the **development** version from +[GitHub](https://github.com/Thinkr-open/squash) with: -Link to quarto: [download page](https://quarto.org/docs/download/) +``` r +remotes::install_github("Thinkr-open/squash", ref = "main") +``` -## How to use it +This package relies on quarto \> 1.3 (see its [download +page](https://quarto.org/docs/download/)). + +## Play with `{squash}` + +### Simple case ``` r library(squash) @@ -98,6 +111,12 @@ unlink(temp_dir, recursive = TRUE) unlink(tmp_course_path, recursive = TRUE) ``` +## Code of Conduct + +Please note that this project is released with a [Contributor Code of +Conduct](https://www.contributor-covenant.org/version/1/0/0/code-of-conduct.html). +By participating in this project you agree to abide by its terms. + ## Devs ### Check From f33ab43984eb7778630d0ec591a9d6cdc66ce806 Mon Sep 17 00:00:00 2001 From: dagousket Date: Mon, 9 Dec 2024 10:53:43 +0000 Subject: [PATCH 4/4] chore: restructure pkgdown --- README.Rmd | 70 +++--------- README.md | 79 ++++---------- pkgdown/_pkgdown.yml | 12 ++- vignettes/advanced-usage-future.Rmd | 81 ++++++++++++++ vignettes/advanced-usage-template.Rmd | 102 ++++++++++++++++++ ...ced-usage.Rmd => advanced-usage-theme.Rmd} | 95 ++-------------- ...t-started.Rmd => simple-example-usage.Rmd} | 38 ++----- 7 files changed, 248 insertions(+), 229 deletions(-) create mode 100644 vignettes/advanced-usage-future.Rmd create mode 100644 vignettes/advanced-usage-template.Rmd rename vignettes/{advanced-usage.Rmd => advanced-usage-theme.Rmd} (52%) rename vignettes/{get-started.Rmd => simple-example-usage.Rmd} (69%) diff --git a/README.Rmd b/README.Rmd index 53c417b..b7c403f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -42,60 +42,17 @@ This package relies on quarto > 1.3 (see its [download page](https://quarto.org/ ## Play with `{squash}` -### Simple case +### TL;DR -```{r} -library(squash) -``` - -Given a vector containing path to several .qmd chapters. +Given a vector `qmds` containing paths to one or several qmd file chapters, you can use the function `compile_qmd_course()` to compile a course. ```{r, eval=FALSE} -# list example qmds from /inst -courses_path <- system.file( - "courses", - "M01", - package = "squash" -) - -# copy example qmds in a tempdir -tmp_course_path <- tempfile(pattern = "course") -dir.create(tmp_course_path) - -file.copy( - from = courses_path, - to = tmp_course_path, - recursive = TRUE -) - -qmds <- list.files( - path = tmp_course_path, - full.names = TRUE, - recursive = TRUE, - pattern = "qmd$" -) - -qmds -``` - -And a directory where you want your course to be generated. - -```{r, eval=FALSE} -# generate html in temp folder -temp_dir <- tempfile(pattern = "compile") -``` - -You can use the function `compile_qmd_course()` to compile a course. - -> We wrap the function call inside a `progressr::with_progress()` to see the progress bar. You can also set it in the console with `progressr::handlers(global = TRUE)` +library(squash) -```{r, eval=FALSE} -html_output <- progressr::with_progress( - compile_qmd_course( - vec_qmd_path = qmds, - output_dir = temp_dir, - output_html = "complete_course.html" - ) +compile_qmd_course( + vec_qmd_path = qmds, + output_dir = tempdir(), + output_html = "complete_course.html" ) ``` @@ -104,12 +61,15 @@ Check out the result browseURL(html_output) ``` -Clean temporary example directory. +### Tutorials -```{r, eval=FALSE} -unlink(temp_dir, recursive = TRUE) -unlink(tmp_course_path, recursive = TRUE) -``` +You can find find a full tutorial on how to create your first `{squash}`-made html [here](https://thinkr-open.github.io/squash/articles/simple-example-usage.html). + +Eager to spice it up ? Take a look at some advanced usage doc : + +- using quarto themes and extensions : [here](https://thinkr-open.github.io/squash/articles/advanced-usage-theme.html) +- using a personalized template : [here](https://thinkr-open.github.io/squash/articles/advanced-usage-template.html) +- using parallel workers with `{future}` : [here](https://thinkr-open.github.io/squash/articles/advanced-usage-future.html) ## Code of Conduct diff --git a/README.md b/README.md index 13b2b14..111361e 100644 --- a/README.md +++ b/README.md @@ -39,62 +39,19 @@ page](https://quarto.org/docs/download/)). ## Play with `{squash}` -### Simple case +### TL;DR -``` r -library(squash) -``` - -Given a vector containing path to several .qmd chapters. - -``` r -# list example qmds from /inst -courses_path <- system.file( - "courses", - "M01", - package = "squash" -) - -# copy example qmds in a tempdir -tmp_course_path <- tempfile(pattern = "course") -dir.create(tmp_course_path) - -file.copy( - from = courses_path, - to = tmp_course_path, - recursive = TRUE -) - -qmds <- list.files( - path = tmp_course_path, - full.names = TRUE, - recursive = TRUE, - pattern = "qmd$" -) - -qmds -``` - -And a directory where you want your course to be generated. +Given a vector `qmds` containing paths to one or several qmd file +chapters, you can use the function `compile_qmd_course()` to compile a +course. ``` r -# generate html in temp folder -temp_dir <- tempfile(pattern = "compile") -``` - -You can use the function `compile_qmd_course()` to compile a course. - -> We wrap the function call inside a `progressr::with_progress()` to see -> the progress bar. You can also set it in the console with -> `progressr::handlers(global = TRUE)` +library(squash) -``` r -html_output <- progressr::with_progress( - compile_qmd_course( - vec_qmd_path = qmds, - output_dir = temp_dir, - output_html = "complete_course.html" - ) +compile_qmd_course( + vec_qmd_path = qmds, + output_dir = tempdir(), + output_html = "complete_course.html" ) ``` @@ -104,12 +61,20 @@ Check out the result browseURL(html_output) ``` -Clean temporary example directory. +### Tutorials -``` r -unlink(temp_dir, recursive = TRUE) -unlink(tmp_course_path, recursive = TRUE) -``` +You can find find a full tutorial on how to create your first +`{squash}`-made html +[here](https://thinkr-open.github.io/squash/articles/simple-example-usage.html). + +Eager to spice it up ? Take a look at some advanced usage doc : + +- using quarto themes and extensions : + [here](https://thinkr-open.github.io/squash/articles/advanced-usage-theme.html) +- using a personalized template : + [here](https://thinkr-open.github.io/squash/articles/advanced-usage-template.html) +- using parallel workers with `{future}` : + [here](https://thinkr-open.github.io/squash/articles/advanced-usage-future.html) ## Code of Conduct diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index ba94624..e89927d 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -32,10 +32,18 @@ navbar: tutos: text: Tutorial menu: + - text: ------- - text: Get started - href: articles/get-started.html + - text: Simple example usage + href: articles/simple-example-usage.html + - text: ------- - text: Advanced usage - href: articles/advanced-usage.html + - text: Using personnalised template + href: articles/advanced-usage-template.html + - text: Using quarto extensions + href: articles/advanced-usage-theme.html + - text: Using parallel workers + href: articles/advanced-usage-future.html footer: structure: diff --git a/vignettes/advanced-usage-future.Rmd b/vignettes/advanced-usage-future.Rmd new file mode 100644 index 0000000..9ee02b8 --- /dev/null +++ b/vignettes/advanced-usage-future.Rmd @@ -0,0 +1,81 @@ +--- +title: "Using parallel workers" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Using parallel workers} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +```{r, eval=FALSE} +#| include: false + +# list example qmds +courses_path <- system.file( + "courses", + "M01", + package = "squash" +) + +# copy course tree in tmpdir, add quarto porject file +tmp_course_path <- tempfile(pattern = "course") +dir.create(tmp_course_path) +file.create(file.path(tmp_course_path, "_quarto.yaml")) + +file.copy( + from = courses_path, + to = tmp_course_path, + recursive = TRUE +) + +qmds <- list.files( + path = tmp_course_path, + full.names = TRUE, + recursive = TRUE, + pattern = "qmd$" +) + +# generate html in temp folder +temp_dir <- tempfile(pattern = "compile") + +``` + +The individual rendering of qmd files is managed with the `{future}` and `{furrr}` packages, meaning you can parallelize the generation of several chapters at once. + +To do so, you need to setup the future `plan()` with your selected behavior (e.g. `sequential` or `multisession`) before running the compilation. + +```{r, eval=FALSE} +library(future) + +# set parallel rendering with future +plan(multisession, workers = 2) + +html_output <- compile_qmd_course( + vec_qmd_path = qmds, + output_dir = temp_dir, + output_html = "complete_course.html" +) + +# reset default future plan +plan("default") +``` + +## A note on future + +Parallel rendering in currently not natively supported by quarto. As a result, please use parallel rendering at your own risk, as it is likely to become unstable with an increasing number of qmd chapter files. + +This is caused by temporary execution directories that may be erased by a sub-process while still being looked for in another subprocess. + +```{r, eval=FALSE} +# clean up +unlink(temp_dir, recursive = TRUE) +unlink(tmp_course_path, recursive = TRUE) +``` + diff --git a/vignettes/advanced-usage-template.Rmd b/vignettes/advanced-usage-template.Rmd new file mode 100644 index 0000000..2cbfc72 --- /dev/null +++ b/vignettes/advanced-usage-template.Rmd @@ -0,0 +1,102 @@ +--- +title: "Using personnalised template" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Using personnalised template} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +```{r, eval=FALSE} +#| include: false + +# list example qmds +courses_path <- system.file( + "courses", + "M01", + package = "squash" +) + +# copy course tree in tmpdir, add quarto porject file +tmp_course_path <- tempfile(pattern = "course") +dir.create(tmp_course_path) +file.create(file.path(tmp_course_path, "_quarto.yaml")) + +file.copy( + from = courses_path, + to = tmp_course_path, + recursive = TRUE +) + +qmds <- list.files( + path = tmp_course_path, + full.names = TRUE, + recursive = TRUE, + pattern = "qmd$" +) + +# generate html in temp folder +temp_dir <- tempfile(pattern = "compile") + +``` + +By default, `{squash}` will include your qmd chapters into a minimal template with no extra slide then the title one. + +You can provide a personalized template, and include some custom placeholder as necessary. + +The only requirement for your template is to keep the `{{ include_html_content }}` placeholder, as it will be the landing spot for including the chapter slides. + +Let's use the following template : + +```{.md} + +{{ include_html_content }} + +--- + + +## {{ trainer }} + +**{{ phone }}** + +**{{ mail }}** +``` + +> This template is available via `system.file("template.qmd", package = "squash")` + +In this template, I add three new placeholders in a last slide to mention a trainer's contact details. + +I can now render my template with customized info in these new slots with the following command : + +```{r, eval=FALSE} +library(squash) + +html_output <- compile_qmd_course( + vec_qmd_path = qmds, + output_dir = temp_dir, + output_html = "complete_course.html", + template = system.file("template.qmd", package = "squash"), + template_text = list( + "trainer" = "Rudolph", + "phone" = "36 15 36 15", + "mail" = "alloperenoel.com" + ) +) +``` + +You can add as many new placeholder as you wish, as long as you provide it with a value in the `template_text` input list. + +You can also add some fixed content directly into the template that will be rendered without the need of extra parameters. + +```{r, eval=FALSE} +# clean up +unlink(temp_dir, recursive = TRUE) +unlink(tmp_course_path, recursive = TRUE) +``` diff --git a/vignettes/advanced-usage.Rmd b/vignettes/advanced-usage-theme.Rmd similarity index 52% rename from vignettes/advanced-usage.Rmd rename to vignettes/advanced-usage-theme.Rmd index bf3b7cb..8f076b5 100644 --- a/vignettes/advanced-usage.Rmd +++ b/vignettes/advanced-usage-theme.Rmd @@ -1,8 +1,8 @@ --- -title: "Advanced usage" +title: "Using quarto extensions" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Advanced usage} + %\VignetteIndexEntry{Using quarto extensions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -14,9 +14,7 @@ knitr::opts_chunk$set( ) ``` -```{r} -#| include: false - +```{r, eval=FALSE} # list example qmds courses_path <- system.file( "courses", @@ -47,59 +45,9 @@ temp_dir <- tempfile(pattern = "compile") ``` -## Using personnalised template - -By default, `{squash}` will include your qmd chapters into a minimal template with no extra slide then the title one. - -You can provide a personalized template, and include some custom placeholder as necessary. - -The only requirement for your template is to keep the `{{ include_html_content }}` placeholder, as it will be the landing spot for including the chapter slides. - -Let's use the following template : - -```{.md} - -{{ include_html_content }} - ---- - - -## {{ trainer }} - -**{{ phone }}** - -**{{ mail }}** -``` - -> This template is available via `system.file("template.qmd", package = "squash")` - -In this template, I add three new placeholders in a last slide to mention a trainer's contact details. - -I can now render my template with customized info in these new slots with the following command : - -```{r, eval=FALSE} -library(squash) - -html_output <- compile_qmd_course( - vec_qmd_path = qmds, - output_dir = temp_dir, - output_html = "complete_course.html", - template = system.file("template.qmd", package = "squash"), - template_text = list( - "trainer" = "Rudolph", - "phone" = "36 15 36 15", - "mail" = "alloperenoel.com" - ) -) -``` - -You can add as many new placeholder as you wish, as long as you provide it with a value in the `template_text` input list. - -You can also add some fixed content directly into the template that will be rendered without the need of extra parameters. - -## Using quarto extensions (theme and plugin) +## Using quarto themes -Let's now say the default quarto theme is somewhat not your style, how could you include your preferred quarto theme ? +Let's say the default quarto theme is somewhat not your style, how could you include your preferred quarto theme ? To do so, you first need to install this extension on your machine like you would do for a single qmd file rendering. @@ -119,6 +67,8 @@ html_output <- compile_qmd_course( ) ``` +## Using quarto plugins + Cool right ? But let's go further and add a plugin in the `_extensions` folders ! ```{.bash} @@ -139,7 +89,7 @@ html_output <- compile_qmd_course( ) ``` -### A note on extensions +## A note on extensions In order to use themes and plugins, you can only provide a single `_extensions` folder via the `ext_dir` parameter, so make sure all the necessary folders are installed in there. @@ -152,37 +102,8 @@ When rendering a qmd file, `{squash}` will make sure the qmd can access the prov In both cases, if the extensions are already present in the target location, a note will be raised in the console and `{squash}` will use the existing extensions without overriting. -## Using parallel workers - -The individual rendering of qmd files is managed with the `{future}` and `{furrr}` packages, meaning you can parallelize the generation of several chapters at once. - -To do so, you need to setup the future `plan()` with your selected behavior (e.g. `sequential` or `multisession`) before running the compilation. - -```{r, eval=FALSE} -library(future) - -# set parallel rendering with future -plan(multisession, workers = 2) - -html_output <- compile_qmd_course( - vec_qmd_path = qmds, - output_dir = temp_dir, - output_html = "complete_course.html" -) - -# reset default future plan -plan("default") -``` - -### A note on future - -Parallel rendering in currently not natively supported by quarto. As a result, please use parallel rendering at your own risk, as it is likely to become unstable with an increasing number of qmd chapter files. - -This is caused by temporary execution directories that may be erased by a sub-process while still being looked for in another subprocess. - ```{r, eval=FALSE} # clean up unlink(temp_dir, recursive = TRUE) unlink(tmp_course_path, recursive = TRUE) ``` - diff --git a/vignettes/get-started.Rmd b/vignettes/simple-example-usage.Rmd similarity index 69% rename from vignettes/get-started.Rmd rename to vignettes/simple-example-usage.Rmd index 9a3d454..2ff090b 100644 --- a/vignettes/get-started.Rmd +++ b/vignettes/simple-example-usage.Rmd @@ -1,8 +1,8 @@ --- -title: "Get started" +title: "Simple example usage" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Get started} + %\VignetteIndexEntry{Simple example usage} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -14,23 +14,13 @@ knitr::opts_chunk$set( ) ``` -## Introduction - -_What is `{squash}` made for?_ - -This package has been developed to enable the generation of a single html presentation file from multiple independent quarto files. - -Given a list of qmd files, `{squash}` will individually render them with the specified metadata and combine their content into a single template file. - -Relative references to image and external data in each single qmd file will be functional and embedded in the final html presentation. - ## How do I use {squash} ? This is a basic example of combining qmd files into a single html presentation. -Let's say we have two folders with qmd files inside, refering to some logo images. +Let's say we have two folders with qmd files inside, alongside their images. -```{r} +```{r, eval=FALSE} #| include: false # list example qmds @@ -49,10 +39,6 @@ file.copy( to = tmp_course_path, recursive = TRUE ) -``` - -```{r} -fs::dir_tree(tmp_course_path) qmds <- list.files( tmp_course_path, @@ -60,13 +46,13 @@ qmds <- list.files( recursive = TRUE, pattern = "qmd$" ) - -qmds ``` +> These files are available for copy via `system.file("courses", "M01", package = "squash")` + I can render a single html presentation from these qmd by executing the following command : -```{r} +```{r, eval=FALSE} library(squash) html_output <- compile_qmd_course( @@ -79,13 +65,7 @@ html_output <- compile_qmd_course( Tada, I now have a new folder, with my complete html presentation alongside the necessary external image files, stored in individual sub-folder to prevent overriding. -```{r} -fs::dir_tree(tmp_course_path, recurse = 2) -``` - -```{r} -#| include: false - +```{r, eval=FALSE} unlink(tmp_course_path, recursive = TRUE) ``` @@ -99,3 +79,5 @@ unlink(tmp_course_path, recursive = TRUE) * {squash} can work both inside and outside of a quarto project, qmd files to combine together can also come from different quarto projects. * In case of failure to render some files, `{squash}` will erase all temporarily created files before exiting. + +* To see a progress bar as compilation is running, you can wrap the function call inside a `progressr::with_progress()`. You can also set it in the console with `progressr::handlers(global = TRUE)`. \ No newline at end of file