more documentation updates

R/Episode.R

@@ -2,9 +2,16 @@
 #'
 #' @description
 #' Wrapper around an xml document to manipulate and inspect Carpentries episodes
+#' 
 #' @details
-#' This class is a fancy wrapper around the results of [tinkr::to_xml()] and
-#' has method specific to the Carpentries episodes.
+#' The Episode class is a superclass of [tinkr::yarn()], which transforms 
+#' (commonmark-formatted) Markdown to XML and back again. The extension that
+#' the Episode class provides is support for both [Pandoc](https://pandoc.org) 
+#' and [kramdown](https://kramdown.gettalong.org/) flavours of Markdown. 
+#' 
+#' Read more about this class in `vignette("intro-episode", package =
+#' "pegboard)`.
+#' 
 #' @export
 Episode <- R6::R6Class("Episode",
   inherit = tinkr::yarn,
@@ -99,7 +106,12 @@ Episode <- R6::R6Class("Episode",
       self$yaml <- ep$yaml
       self$body <- ep$body
       self$ns   <- ep$ns
+      # if the parents are missing, this walk will do nothing
       purrr::walk(parents, function(parent) add_parent(self, parent))
+      # the parent here is used to determine the build path for the
+      # child document, which is dependent on the build parent, aka the final
+      # ancestor. If there is no parent, then the children are relative to the
+      # parent.
       self$children <- find_children(ep, ancestor = parents[[1]])
     },
 

R/Lesson.R

@@ -2,10 +2,17 @@
 #'
 #' @description
 #' This is a wrapper for several [Episode] class objects.
+#' 
 #' @details
-#' Lessons are made of up several episodes within the `_episodes/` directory of
-#' a lesson. This class keeps track of several episodes and allows us to switch
-#' between RMarkdown and markdown episodes
+#' 
+#' This class contains and keeps track of relationships between [Episode]
+#' objects contained within [Carpentries
+#' Workbench](https://carpentries.github.io/workbench) and [Carpentries 
+#' styles](https://carpentries.github.io/lesson-example) lessons. 
+#'
+#' Read more about how to use this class in `vignette("intro-lesson", package =
+#' "pegboard")`
+#'
 #' @export
 Lesson <- R6::R6Class("Lesson",
   public = list(

vignettes/intro-lesson.Rmd

@@ -195,7 +195,8 @@ lapply(wb_lesson$built, class)
 ```
 
 You can use these to inspect how the content is rendered and see that the
-code blocks render what they should render:
+code blocks render what they should render. In thise case, `episodes/intro.Rmd`
+will render one output block and one image.
 
 ```{r summary-built}
 to_check <- c("page", "code", "output", "images", "warning", "error")