Merge pull request #583 from tidymodels/doc-tools

Update how-to for engine documentation

Author: hfrick

R/aaa_models.R

@@ -1054,11 +1054,11 @@ get_encoding <- function(model) {
 #' based on which parsnip-related packages are loaded by the user.
 #'
 #' These functions can be used to make dynamic lists of documentation help
-#'  files. \pkg{parsnip} uses these, along with files contained in `man/rmd`
-#'  containing expanded documentation, for specific model/engine combinations.
+#'  files. \pkg{parsnip} uses these along with files in `man/rmd` which
+#'  contain expanded documentation for specific model/engine combinations.
 #'  [find_engine_files()] looks for files that have the pattern
 #'  `details_{model}_{engine}.Rd` to link to. These files are generated by files
-#'  named `man/rmd/details_{model}_{engine}.Rmd`. `make_engine_list()` creates a
+#'  named `man/rmd/{model}_{engine}.Rmd`. `make_engine_list()` creates a
 #'  list seen at the top of the model Rd files while `make_seealso_list()`
 #'  populates the list seen in "See Also" below. See the details section.
 #'
@@ -1083,18 +1083,18 @@ get_encoding <- function(model) {
 #'
 #'   1. Create an engine-specific R file in the `R` directory with the name
 #'  `{model}_{engine}.R` (e.g. `boost_tree_C5.0.R`). This has a small amount of
-#'  documentation, as well as the directive
-#'  "`@includeRmd man/rmd/{model}_{engine}.Rmd details`".
+#'  documentation, as well as the directives "`@name details_{model}_{engine}`"
+#'  and "`@includeRmd man/rmd/{model}_{engine}.Rmd details`".
 #'
-#'   1. Copy the file in \pkg{parsnip} that is in `man/rmd/setup.Rmd` and put
+#'   2. Copy the file in \pkg{parsnip} that is in `man/rmd/setup.Rmd` and put
 #'  it in the same place in your package.
 #'
-#'   1. Write your own `man/rmd/{model}_{engine}.Rmd` file. This can include
+#'   3. Write your own `man/rmd/{model}_{engine}.Rmd` file. This can include
 #'  packages that are not listed in the DESCRIPTION file. Those are only
 #'  required when the documentation file is created locally (probably using
-#'  [devtools::document()].
+#'  [devtools::document()]).
 #'
-#'   1. Run [devtools::document()] so that the Rmd content is included in the
+#'   4. Run [devtools::document()] so that the Rmd content is included in the
 #'  Rd file.
 #'
 #' The examples in \pkg{parsnip} can provide guidance for how to organize

man/doc-tools.Rd

@@ -15,12 +15,12 @@ convert_args <- function(model_name) {
     dplyr::filter(grepl(model_name, model)) %>%
     tidyr::unnest(args) %>%
     dplyr::select(model:original) %>%
-    full_join(get_arg_defaults(model_name),
-              by = c("model", "engine", "parsnip", "original")) %>%
-    mutate(original = dplyr::if_else(!is.na(default),
-                                     paste0(original, " (", default, ")"),
-                                     original)) %>%
-    select(-default)
+    dplyr::full_join(get_arg_defaults(model_name),
+                     by = c("model", "engine", "parsnip", "original")) %>%
+    dplyr::mutate(original = dplyr::if_else(!is.na(default),
+                                            paste0(original, " (", default, ")"),
+                                            original)) %>%
+    dplyr::select(-default)
 
   convert_df <- args %>%
     dplyr::select(-model) %>%
@@ -53,11 +53,11 @@ get_dials <- function(x) {
 }
 
 descr_models <- function(mod, eng) {
-  res <- get_from_env(mod) %>% 
-    dplyr::filter(engine == eng) %>% 
-    dplyr::distinct() %>% 
+  res <- get_from_env(mod) %>%
+    dplyr::filter(engine == eng) %>%
+    dplyr::distinct() %>%
     purrr::pluck("mode")
-  
+
   if (length(res) == 1) {
     txt <- "is a single mode:"
   } else {