Add section on literate programming limitations

NEWS.md

@@ -1,6 +1,7 @@
 # tarchetypes 0.7.10.9000 (development)
 
 * Use `tar_seed_create()` and `tar_seed_set()` from `targets`.
+* Document limitations of literate programming target factories like `tar_render()` (#158).
 
 # tarchetypes 0.7.10
 

R/tar_quarto.R

@@ -27,6 +27,7 @@
 #'       instead of the working directory of the report.
 #'     5. Sets convenient default options such as `deployment = "main"`
 #'       in the target and `quiet = TRUE` in `quarto::quarto_render()`.
+#' @inheritSection tar_render Literate programming limitations
 #' @section Quarto troubleshooting:
 #'   If you encounter difficult errors, please read
 #'   <https://github.com/quarto-dev/quarto-r/issues/16>.

R/tar_quarto_raw.R

@@ -19,6 +19,7 @@
 #'   without invalidating the target).
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
+#' @inheritSection tar_render Literate programming limitations
 #' @inheritSection tar_quarto Quarto troubleshooting
 #' @inheritParams targets::tar_target_raw
 #' @inheritParams quarto::quarto_render

R/tar_quarto_rep.R

@@ -38,6 +38,7 @@
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
 #' @inheritSection tar_rep Replicate-specific seeds
+#' @inheritSection tar_render Literate programming limitations
 #' @inheritSection tar_quarto Quarto troubleshooting
 #' @inheritParams tar_rep
 #' @inheritParams targets::tar_target

R/tar_quarto_rep_raw.R

@@ -43,6 +43,7 @@
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
 #' @inheritSection tar_rep Replicate-specific seeds
+#' @inheritSection tar_render Literate programming limitations
 #' @inheritSection tar_quarto Quarto troubleshooting
 #' @inheritParams tar_rep
 #' @inheritParams quarto::quarto_render

R/tar_render.R

@@ -24,6 +24,18 @@
 #'       instead of the working directory of the report.
 #'     5. Sets convenient default options such as `deployment = "main"`
 #'       in the target and `quiet = TRUE` in `rmarkdown::render()`.
+#' @section Literate programming limitations:
+#'   Literate programming files are messy and variable,
+#'   so functions like [tar_render()] have limitations:
+#'     * Child documents are not tracked for changes.
+#'     * Upstream target dependencies are not detected if [tar_read()]
+#'       and/or [tar_load()] are called from a user-defined function.
+#'       In addition, single target names must be mentioned and they must
+#'       be symbols. `tar_load("x")` and `tar_load(contains("x"))` may not
+#'       detect target `x`.
+#'     * Special/optional input/output files may not be detected in all cases.
+#'     * [tar_render()] and friends are for local files only. They do not
+#'       integrate with the cloud storage capabilities of `targets`.
 #' @return A target object with `format = "file"`.
 #'   When this target runs, it returns a character vector
 #'   of file paths: the rendered document, the source file,

R/tar_render_raw.R

@@ -17,6 +17,7 @@
 #'   without invalidating the target).
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
+#' @inheritSection tar_render Literate programming limitations
 #' @inheritParams tar_render
 #' @param name Character of length 1, name of the target.
 #' @param render_arguments Optional language object with a list

R/tar_render_rep.R

@@ -37,6 +37,7 @@
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
 #' @inheritSection tar_rep Replicate-specific seeds
+#' @inheritSection tar_render Literate programming limitations
 #' @inheritParams tar_rep
 #' @inheritParams targets::tar_target
 #' @inheritParams rmarkdown::render

R/tar_render_rep_raw.R

@@ -42,6 +42,7 @@
 #'   See the "Target objects" section for background.
 #' @inheritSection tar_map Target objects
 #' @inheritSection tar_rep Replicate-specific seeds
+#' @inheritSection tar_render Literate programming limitations
 #' @inheritParams targets::tar_target
 #' @inheritParams rmarkdown::render
 #' @inheritParams tar_rep