Create _pkgslides.yml

_pkgslides.yml is at the core of pkgslides and is used to customize your presentation exactly how you want it.

We provide create_yaml() as an interface to get you started, or you can create one from scratch. We generally recommend using create_yaml() for packages you may not have already while you can use an existing file for packages you built or keep source code for. Of course, for the second option, you can always create the file with create_yaml().

Creating `_pkgslides.yml`

Before we get started with any examples, let’s load pkgslides.

library(pkgslides)

Example 1: `palmerpenguins`

Let’s first check to see what palmerpenguins exports.

library(palmerpenguins)
ls("package:palmerpenguins")
#> [1] "path_to_file" "penguins"     "penguins_raw"

We see that it has three exports. The first, path_to_file is a function, while penguins and penguins_raw are both datasets.

Let’s say we want to include everything that is exported by palmerpenguins. For each function we want a description of what it does, what it returns, and what parameters it takes. For each dataset we want to know what format the data is in and what sources it came from. We’ll leave the theme as-is for now.

We don’t actually need to include any lines that are TRUE as that is the default case, but we’ll leave it in for now for the sake of clarity.

format:
  theme: default
  functions:
    description: TRUE
    returns: TRUE
    parameters: TRUE
    examples: FALSE
    code: FALSE
  datasets:
    format: TRUE
    source: TRUE
    references: FALSE
functions: all
datasets: all

One extra thing to be aware of when using create_yaml() is that we need to provide a folder path for _pkgslides.yml to live at. For now, we’ll create it in our current working directory, represented by ".". Like above, we’re going to explicitly declare all of our options, even if we want the default case.

create_yaml(
  path = ".",
  format_theme = c("default"),
  format_functions = list(
    description = TRUE,
    returns = TRUE,
    parameters = TRUE,
    examples = FALSE,
    code = FALSE
  ),
  format_datasets = list(
    format = TRUE,
    source = TRUE,
    references = TRUE
  ),
  choose_functions = list("all"),
  choose_datasets = list("all")
)
#> Config written to './_pkgslides.yml'
#> ./_pkgslides.yml

We can then double check our new yaml file. We pull in the file with yaml::read_yaml() then convert the list into a string with yaml::as.yaml(). Finally, we print with formatting with cat(). You may notice that our TRUE and FALSE choices have been replaced withyes and no. As it turns out, yaml files accept both as valid options. You may also notice that while the sections may not be in the same order, they retain the same tree structure. Other than that, our generated _pkgslides.yml is the same as the one we made by hand.

yaml::read_yaml("_pkgslides.yml") |> 
  yaml::as.yaml() |> 
  cat()
#> format:
#>   functions:
#>     return: yes
#>     description: yes
#>     parameters: yes
#>     examples: no
#>     code: no
#>   datasets:
#>     format: yes
#>     source: yes
#>     references: yes
#>   theme: default
#> functions:
#> - file: all
#> datasets: all

Example 2: `pkgslides`

This example generates a pkgslides presentation for itself. We don’t need any source code, but want the rest of the function slides. We also specify that we want to automatically choose slides from yaml.R which will include all functions. The auto option produces slides for internal functions only if they are in the same file as an exported function. Thus, when used on a single file, it produces the same result as all. We then specify that we only want the .get_title() and .collate_title() functions from build_title.R and all functions from build_presentation.R.

format:
  functions:
    code: false
functions:
  - file: yaml.R
    slides: auto
  - file: build_title.R # will only include functions in slides
    slides:
      - .get_title
      - .collate_title
  - file: build_presentation.R # will include all functions

Like in Example 1, we’re going to generate _pkgslides.yml in our current working directory with ".", but since that’s the default, we won’t specify it.

create_yaml(
  format_functions = list(
    code = FALSE
  ),
  format_datasets = list(
    format = TRUE,
    source = TRUE,
    references = TRUE
  ),
  choose_functions = list(
    "yaml.R" = "auto",
    "build_title.R" = c(".get_title", ".collate_title"),
    "build_presentation.R"
  )
)
#> Config written to '/Users/guslipkin/Documents/GitHub/pkgslides/vignettes/_pkgslides.yml'
#> /Users/guslipkin/Documents/GitHub/pkgslides/vignettes/_pkgslides.yml

Again, we can check our file and see that while the formatting is slightly different and all options are now present, it yields the same data.

yaml::read_yaml("_pkgslides.yml") |> 
  yaml::as.yaml() |> 
  cat()
#> format:
#>   functions:
#>     description: yes
#>     return: yes
#>     parameters: yes
#>     examples: yes
#>     code: no
#>   datasets:
#>     format: yes
#>     source: yes
#>     references: yes
#>   theme: default
#> functions:
#> - file: yaml.R
#>   slides: auto
#> - file: build_title.R
#>   slides:
#>   - .get_title
#>   - .collate_title
#> - file: build_presentation.R
#>   slides: all
#> datasets: all

All Options

Any line listed with curly braces such as {true, false} mean that one and only one of those options should be chosen.

For the sake of example, generic names have been used for source files, function names, and dataset names.

format:
  theme: default
  functions:
    parameters: {true, false}
    examples: {true, false} # target package must be installed to evaluate
    code: {true, false}
    # tests: {true, false} currently unsupported
  datasets:
    format: {true, false}
    source: {true, false}
    references: {true, false}
    # view: {true, false} currently unsupported

functions:
  - file: source1.R # will only include functions in slides
    slides:
      - function1
      - function2
  - file: source2.R # will include all functions
  - file: source3.R
    slides: auto

datasets:
  - dataset1
  - dataset2

---

# Other options

format:
  # lack of `functions:`
# Excluding the `functions:` section is the same as setting all slides to 'true'. 
#   This will show all slides for which content exists.

format:
  theme: {default, ...}
# see https://quarto.org/docs/presentations/revealjs/themes.html#using-themes
# this is passed directly to the quarto document

functions: {auto, exported, all, none}
# 'auto' uses exported functions and internal functions in the same file as an 
#   exported function
# 'exported' uses only exported functions
# 'all' The default behavior, but should be there if the yml file exists

datasets: {all, none}
# 'all' The default behavior, but should be there if the yml file exists
# 'none' No datasets will be included

Creating _pkgslides.yml

Example 1: palmerpenguins

Example 2: pkgslides

All Options

Creating `_pkgslides.yml`

Example 1: `palmerpenguins`

Example 2: `pkgslides`