Merge pull request #4 from ThinkR-open/add-vignette

doc: update pkgdown vignettes

.gitignore

@@ -8,4 +8,3 @@ index_files
 inst/doc
 inst/**/*_files/
 docs/
-pkgdown/favicon/

pkgdown/_pkgdown.yml

@@ -26,15 +26,15 @@ navbar:
   bg: info
   type: light
   structure:
-    left: [tutos]
+    left: [reference, tutos, news]
     right: [github]
   components:
     tutos:
       text: Tutorial
       menu:
-      - text: Getting started
+      - text: Get started
         href: articles/get-started.html
-      - text: Advanced
+      - text: Advanced usage
         href: articles/advanced-usage.html
 
 footer:

pkgdown/favicon/site.webmanifest

@@ -0,0 +1,21 @@
+{
+  "name": "",
+  "short_name": "",
+  "icons": [
+    {
+      "src": "/web-app-manifest-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/web-app-manifest-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}

vignettes/advanced-usage.Rmd

@@ -49,37 +49,138 @@ temp_dir <- tempfile(pattern = "compile")
 
 ## Using personnalised template
 
-## Using quarto extensions
+By default, `{squash}` will include your qmd chapters into a minimal template with no extra slide then the title one.
 
-> A note on extensions and projects
+You can provide a personalized template, and include some custom placeholder as necessary.
 
-## Using parallel workers
+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.
 
-```{r}
+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)
-library(future)
 
-# set parallel rendering
-plan(multisession, workers = 2)
+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)
+
+Let's now 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.
+
+```{.bash}
+quarto add ArthurData/quarto-revealjs-lilleuniv
+```
+
+Great, now you can use this theme with `{squash}` by providing the target theme as `output_format` and the `_extensions` folder path as `ext_dir`.
+
+```{r, eval=FALSE}
 html_output <- compile_qmd_course(
   vec_qmd_path = qmds,
   output_dir = temp_dir,
-  output_html = "complete_course.html"
+  output_html = "complete_course.html",
+  output_format = "revealjs-lille-univ-dark-revealjs",
+  ext_dir = "path/to/_extensions"
 )
+```
 
+Cool right ? But let's go further and add a plugin in the `_extensions` folders !
 
+```{.bash}
+quarto add ArthurData/quarto-confetti
 ```
 
+I can now add this plugin in the rendering metadata to integrate it in my presentation.
 
-> A note of caution
+```{r, eval=FALSE}
+html_output <- compile_qmd_course(
+  vec_qmd_path = qmds,
+  output_dir = temp_dir,
+  output_html = "complete_course.html",
+  metadata_template = list(
+    `revealjs-plugins` = c("confetti")
+  ),
+  ext_dir = "path/to/_extensions"
+)
+```
 
-```{r}
-#| include: false
+### 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.
+
+You can edit the metadata a the template level (`metadata_template` input) and/or the qmd level (`metadata_qmd` input). It is usually best for plugins and themes to be applied at the template level (which will be source of the main html output file).
+
+When rendering a qmd file, `{squash}` will make sure the qmd can access the provided `_extensions` folder. Two scenarios can be triggered :
+
+- the qmd is part of a quarto project : the `_extensions` folder is copied in the quarto project root and cleaned after rendering
+- the qmd is **not** part of a quarto project : the `_extensions` folder is copied in the qmd folder and cleaned after rendering
+
+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.
 
-# reset default rendering
+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)

vignettes/get-started.Rmd

@@ -63,6 +63,7 @@ qmds <- list.files(
 
 qmds
 ```
+
 I can render a single html presentation from these qmd by executing the following command :
 
 ```{r}
@@ -76,7 +77,7 @@ html_output <- compile_qmd_course(
 )
 ```
 
-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.
+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)
@@ -93,8 +94,8 @@ unlink(tmp_course_path, recursive = TRUE)
 
 * Files will be included in the same order provided to `compile_qmd_course`.
 
-* Metadata and parameters set in the `compile_qmd_course` will supersed the parameters detected inside the qmd header and/or the quarto project metadata files.
+* Metadata and parameters set in the `compile_qmd_course` will supersede the parameters detected inside the qmd header and/or the quarto project metadata files.
 
-* {squash} can work both inside and outside of a quarto project, qmd files to combine togather can also come from different quarto projects.
+* {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.