update docs (#42)

* update docs

* harmonize function-documentation

* rename vignettes

* add checklist for adding new service

* first pass at embed vignette

* clean up

* Add sample videos

* smol edit

* begin getting-started

* finish vignette("modify"), update others

* start work on README, reorganize others

* finish get-started vignette

.Rbuildignore

@@ -7,5 +7,7 @@
 ^cran-comments\.md$
 ^codecov\.yml$
 ^_pkgdown\.yml$
+^pkgdown$
 ^docs$
 ^\.github$
+^checklist-new-service\.md$

NAMESPACE

@@ -10,7 +10,6 @@ S3method(use_start_time,vembedr_embed_channel9)
 S3method(use_start_time,vembedr_embed_vimeo)
 S3method(use_start_time,vembedr_embed_youtube)
 export("%>%")
-export(build_suggestion)
 export(embed_box)
 export(embed_channel9)
 export(embed_url)

R/div.R

@@ -1,7 +1,7 @@
 #' Align horizontally
 #'
-#' Use this function to specify the horizontal alignment of the `<iframe/>`
-#' within the enclosing `</div>`.
+#' Use this function to specify the horizontal alignment of the `iframe`
+#' within the enclosing `div`.
 #'
 #' @inheritParams use_start_time
 #' @param align `character`, indicates type of alignment
@@ -26,10 +26,10 @@ use_align <- function(embed,
 
 #' Make size responsive
 #'
-#' If your 'HTML` page includes
+#' If your HTML page includes
 #' [Twitter Bootstrap 3](https://getbootstrap.com/docs/3.3/components/#responsive-embed),
-#' you can use this function to make the size of the `<iframe/>` responsive
-#' within the enclosing `</div>`.
+#' you can use this function to make the size of the `iframe` responsive
+#' within the enclosing `div`.
 #'
 #' @inheritParams use_start_time
 #'
@@ -109,8 +109,5 @@ use_rounded <- function(embed, radius = NULL) {
 
   embed[["children"]][[1]] <- div
 
-  # attach html-dependency
-  embed <- htmltools::attachDependencies(embed, vembedr_dependency)
-
   embed
 }

R/embed.R

@@ -1,8 +1,8 @@
-#' Embed a video into an HTML document
+#' Embed video from service
 #'
 #' These functions are used to embed video into your \strong{rmarkdown} html-documents,
 #' or into your \strong{shiny} apps. There are functions to embed from
-#' YouTube, Vimeo, and Microsoft Channel 9 (who host the UseR! 2016 videos).
+#' YouTube, Vimeo, Microsoft Channel 9 (who host the UseR! 2016 videos), and Box.
 #'
 #' These services allow you to customize a lot of things by specifying
 #' an optional query string. The specification for the query string will differ
@@ -16,21 +16,20 @@
 #'   \item{Box}{<https://developer.box.com/docs/box-embed#section-build-box-embed-programatically>}
 #' }
 #'
-#' @param id                character, identifier provided by the service
-#' @param custom_domain     character, (used by Box) name of Box-instance
+#' @param id                `character`, identifier provided by the service
+#' @param custom_domain     `character`, (used by Box) name of Box-instance
 #'   to use. It can be useful to use `getOption("vembedr.box_custom_domain")`
 #'   if you are using a corporate instance of Box. If `NULL`, it will use
 #'   the standard Box instance.
-#' @param height            numeric, height of iframe (px)
-#' @param width             numeric, width of iframe (px)
+#' @param height            `numeric`, height of iframe (px)
+#' @param width             `numeric`, width of iframe (px)
 #' @param ratio             `character`, indicates aspect ratio for the `<iframe/>`
-#' @param frameborder       numeric, size of frame border (px)
-#' @param allowfullscreen   logical, indicates if to allow fullscreen
-#' @param query             list of items to include in url-query string
-#' @param fragment          character, string to include as url-fragment
+#' @param frameborder       `numeric`, size of frame border (px)
+#' @param allowfullscreen   `logical`, indicates if to allow fullscreen
+#' @param query             `list`, items to include in url-query string
+#' @param fragment          `character`, string to include as url-fragment
 #'
-#' @return object with class `vembedr_embed`,
-#'   prints to an 'HTML' `<div/>` that contains an `<iframe/>`
+#' @return Object with S3 class `vembedr_embed`
 #'
 #' @name embed
 #' @family embed
@@ -214,7 +213,7 @@ embed_box <- function(id, custom_domain = getOption("vembedr.box_custom_domain")
   embed
 }
 
-
+# internal function to create embed div
 create_embed <- function(iframe, name, ratio) {
 
   embed <- htmltools::div(
@@ -226,5 +225,8 @@ create_embed <- function(iframe, name, ratio) {
 
   attr(embed, "ratio") <- ratio
 
+  # attach html-dependency
+  embed <- htmltools::attachDependencies(embed, vembedr_dependency())
+
   embed
 }

R/embed_url.R

@@ -1,16 +1,14 @@
-#' Embed a video based on URL
+#' Embed video based on URL
 #'
 #' You can use this function to embed video using only the URL and you do not
-#' need any customization beyond the start-time.
-#' It should work for all the services supported by the [embed()]
-#' family of functions.
+#' need any customization beyond the start-time. It works for all the
+#' services supported by the [embed()] family of functions.
 #'
 #' This function calls [suggest_embed()] then parses and evaluates the code.
-#' If you need to customize the iframe, [suggest_embed()] may be more useful to you.
 #'
-#' @param url character, URL of webpage for video
+#' @param url `character`, URL of web-page for video
 #'
-#' @return An embed object that prints an \code{htmltools::\link[htmltools]{tags}$iframe} element
+#' @inherit embed return
 #'
 #' @seealso [suggest_embed()]
 #' @examples

R/helper.R

@@ -21,6 +21,8 @@
 #' @return numeric, number of seconds
 #'
 #' @seealso [embed_youtube()], [hms()]
+#'
+#' @keywords internal
 #' @export
 #
 secs <- function(x){
@@ -66,6 +68,8 @@ secs <- function(x){
 #'
 #' @return character string (i.e. "0h3m15s")
 #' @seealso [secs()]
+#'
+#' @keywords internal
 #' @export
 #'
 hms <- function(x){

R/parse.R

@@ -1,4 +1,4 @@
-#' Suggest embedding-code based on a URL
+#' Suggest embed-code based on URL
 #'
 #' This function is meant to work with URLs from any of the supported services.
 #'
@@ -11,8 +11,7 @@
 #'     that represents the suggested code}
 #' }
 #'
-#' @param url    character, can be copied from browser location or from
-#'   the "share" output on a video's web page
+#' @inheritParams embed_url
 #'
 #' @return character, returns the suggested code (`suggest_embed` returns invisibly)
 #'
@@ -79,7 +78,7 @@ suggest_embed_pure <- function(url){
 #' @examples
 #' parse_video_url("https://youtu.be/1-vcErOPofQ?t=28s") %>%
 #' build_suggestion()
-#' @export
+#' @noRd
 #'
 build_suggestion <- function(parse_list){
 
@@ -112,11 +111,11 @@ build_suggestion <- function(parse_list){
   suggest_list
 }
 
-#' Determine the service, given the URL
+#' Determine service based on URL
 #'
-#' @inheritParams suggest_embed
+#' @inheritParams embed_url
 #'
-#' @return `character` identfying the video service
+#' @return `character` identifying the video service
 #'
 #' @examples
 #' get_service("https://youtu.be/1-vcErOPofQ?t=28s")

R/pipe.R

@@ -8,6 +8,9 @@
 #' @rdname pipe
 #' @export
 #' @param lhs,rhs An embed object and a function to apply to it
+#'
+#' @keywords internal
+#'
 #' @examples
 #' # Instead of
 #' use_start_time(rickroll_youtube(), "1m35s")

R/rickroll.R

@@ -1,4 +1,4 @@
-#' Embed a popular video
+#' Embed popular video
 #'
 #' If you want to experiment with the arguments to [embed()],
 #' such as `query`, but do not have a particular video in mind, this function

R/s3-classes.R

@@ -0,0 +1,20 @@
+#' vembedr S3 Classes
+#'
+#' We use S3 classes to distinguish an embed object, and to denote which service it uses.
+#'
+#' **`vembedr_embed`**
+#'
+#' - base class for all services
+#' - HTML `<div>`
+#' - contains the embed code
+#'
+#' **`vembedr_embed_youtube`**
+#' **`vembedr_embed_youtube_short`**
+#' **`vembedr_embed_vimeo`**
+#' **`vembedr_embed_channel9`**
+#' **`vembedr_embed_box`**
+#'
+#' @name vembedr-s3-classes
+#'
+NULL
+

R/use_start_time.R

@@ -1,4 +1,4 @@
-#' Specify a start time for an embedded video
+#' Specify start time
 #'
 #' This function provides you a consistent way to specify the start time,
 #' regardless of the service. Please note that Box does not provide a
@@ -15,13 +15,13 @@
 #'
 #' Please note that for Vimeo, you can specify a start time, but you can not
 #' specify that the video be paused at this time. In other words, it is like
-#' "autoplay" is set to TRUE, and you cannot unset it.
+#' "autoplay" is set to `TRUE`, and you cannot unset it.
 #'
 #' @rdname use_start_time
 #' @param ...         generic arguments to pass through
 #' @param embed       `vembedr_embed` object, created using an [embed()] function
-#' @param start_time  numeric (seconds), or character (e.g. `"3m15s"`)
-#' @param is_paused   logical, for "Channel 9" specifies if the video
+#' @param start_time  `numeric` (seconds), or `character` (e.g. `"3m15s"`)
+#' @param is_paused   `logical`, for "Channel 9" specifies if the video
 #'   should be paused at this time
 #'
 #' @inherit embed return
@@ -31,13 +31,13 @@
 #'   rickroll_youtube() %>%
 #'     use_start_time("3m32s")
 #'
-use_start_time <- function(...) UseMethod("use_start_time")
+use_start_time <- function(embed, ...) UseMethod("use_start_time")
 
 
 #' @rdname use_start_time
 #' @export
 #'
-use_start_time.default <- function(...) "Unknown class"
+use_start_time.default <- function(embed, ...) "Unknown class"
 
 #' @rdname use_start_time
 #' @export
@@ -130,6 +130,7 @@ use_start_time.vembedr_embed_channel9 <- function(embed, start_time, is_paused =
 #' @export
 #'
 use_start_time.vembedr_embed_box <- function(embed, ...) {
+
   warning("Start time cannot be specified for Box.")
 
   embed

R/utils-htmltools.R

@@ -10,11 +10,12 @@ to_html_class <- function(x, ...) {
 }
 
 # define html-dependency
-vembedr_dependency <-
+vembedr_dependency <- function() {
   htmltools::htmlDependency(
     name = "vembedr",
-    version = packageVersion("vembedr"),
+    version = utils::packageVersion("vembedr"),
     src = "vembedr",
     stylesheet = c("css/vembedr.css"),
     package = "vembedr"
   )
+}

R/utils-null.R

@@ -1 +1 @@
-`%||%` <- rlang::`%||%`
+#' @importFrom rlang `%||%`

R/vembedr-package.R

@@ -0,0 +1,23 @@
+#' vembedr: Package for embedding video
+#'
+#' The vembedr package lets you embed video into your HTML pages for
+#' these services:
+#'
+#'  - YouTube
+#'  - Vimeo
+#'  - Microsoft Channel 9
+#'  - Box
+#'
+#' It provides two categories of functions:
+#'
+#'  - **embed** functions, to specify a video to embed:
+#'      e.g. [embed_youtube()], [embed_url()]
+#'  - **use** functions, to modify the embedding:
+#'      e.g. [use_start_time()], [use_rounded()]
+#'
+#'  You can use the pipe (`%>%`) to chain embed function-calls with
+#'  use function-calls.
+#'
+#' @docType package
+#' @name vembedr-package
+NULL