changes for #647 (#666)

* changes for #647

* Clarify docs in engine-docs

* Fix quotes

* Clarify README-DOCS

Co-authored-by: Julia Silge <julia.silge@gmail.com>

Author: topepo

R/engine_docs.R

@@ -97,20 +97,24 @@ update_model_info_file <- function(path = "inst/models.tsv") {
 # ------------------------------------------------------------------------------
 
 
-#' Tools for documenting packages
+#' Tools for documenting engines
 #'
 #' @description
-#' These are functions used to create dynamic documentation in Rd files
-#' based on which parsnip-related packages are loaded by the user.
+#' parsnip has a fairly complex documentation system where the engines for
+#'  each model have detailed documentation about the syntax, tuning parameters,
+#'  preprocessing needs, and so on.
 #'
-#' These functions can be used to make dynamic lists of documentation help
-#'  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/{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.
+#' The functions below are called from `.R` files to programmatically
+#'  generate content in the help files for a model.
+#'
+#'   * [find_engine_files()] identifies engines for a model and creates a
+#'  bulleted list of links to those specific help files.
+#'
+#'   * [make_seealso_list()] creates a set of links for the "See Also" list at
+#'  the bottom of the help pages.
+#'
+#'   * [find_engine_files()] is a function, used by the above, to find the
+#'  engines for each model function.
 #'
 #' @param mod A character string for the model file (e.g. "linear_reg")
 #' @param pkg A character string for the package where the function is invoked.
@@ -122,38 +126,23 @@ update_model_info_file <- function(path = "inst/models.tsv") {
 #'
 #' `find_engine_files()` returns a tibble.
 #' @details
-#' The \pkg{parsnip} documentation is generated _dynamically_. Part of the Rd
-#'  file populates a list of engines that depends on what packages are loaded
-#'  *at the time that the man file is loaded*. For example, if
-#'  another package has a new engine for `linear_reg()`, the
-#'  `parsnip::linear_reg()` help can show a link to a detailed help page in the
-#'  other package.
-#'
-#' The process for a package developer to create \pkg{parsnip} documentation is:
-#'
-#'   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 directives "`@name details_{model}_{engine}`"
-#'  and "`@includeRmd man/rmd/{model}_{engine}.md details`".
+#' parsnip includes a document (`README-DOCS.md`) with step-by-step instructions
+#' and details. See the code below to determine where it is installed (or see
+#' the References section).
 #'
-#'   2. Copy the file in \pkg{parsnip} that is in `man/rmd/aaa.Rmd` and put
-#'  it in the same place in your package.
-#'
-#'   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()]).
-#'
-#'   4. Run [devtools::document()] so that the `.md` content is included in the
-#'  Rd file.
-#'
-#' The examples in \pkg{parsnip} can provide guidance for how to organize
-#' technical information about the models.
+#' Most parsnip users will not need to use these functions or documentation.
+#' @references
+#' \url{https://github.com/tidymodels/parsnip/blob/main/inst/README-DOCS.md}
 #' @name doc-tools
 #' @keywords internal
 #' @export
 #' @examples
-#' find_engine_files("linear_reg")
+#' # See this file for step-by-step instructions.
+#' system.file("README-DOCS.md", package = "parsnip")
+#'
+#' # Code examples:
+#' make_engine_list("linear_reg")
+#'
 #' cat(make_engine_list("linear_reg"))
 find_engine_files <- function(mod) {
   # Get available topics

inst/README-DOCS.md

@@ -1,5 +1,7 @@
 # About the parsnip documentation system
 
+## Background
+
 parsnip uses three concepts to describe models: 
 
  - The _model type_ specifies its mathematical structure.
@@ -21,9 +23,23 @@ Each modeling function defined in parsnip has a documentation file (with extensi
 
 Also, each combination of engine and model type has a corresponding `.Rd` file (a.k.a the "engine-specific" documentation files). The list of known engines is also shown in the `.Rd` file for the main function. 
 
+If you are creating a new engine documentation file, the steps are:
+
+1. Use roxygen comments to generate the main `.Rd` file that R's help system uses.
+2. Create an `.Rmd` file that has the details of the engine. 
+3. Knit the `.Rmd` file to `.md` so the `.Rd` file from step 1 can link it. 
+4. Once you are done, run `devtools::document()` (or use the RStudio IDE) to build the help files. 
+
+**Before you read the rest**, you probably don't have to generate the help files in this way yourself: 
+
+* This process only applies for engines whose model function is in parsnip. If your R package defines a new model, then you don't have to do all of this (unless you want to). 
+
+* If you make a PR with a new engine, you can work on the `.Rmd` file and the tidymodels folks can go through the process of merging it in (but let us know if you want us to do that in the PR). 
 
 ## Creating the engine-specific `.Rd` files
 
+Once create by `document()`, the `.Rd` files live in the `man` directory. They are not handwritten but are automatically generated from `.R` files in the `R` directory. 
+
 How do we generate these `.Rd` files? We'll use an example with `poisson_reg()` and the `"zeroinfl"` engine. 
 
 Each model/engine combination has its own `.R` file with a naming convention reflecting the contents (`poisson_reg_zeroinfl.R`). This file has a description of the type of model and the underlying function that is used for that engine: 
@@ -40,15 +56,46 @@ as well as a directive for the `.Rd` file name to be created:
  
 The engine markdown file (`poisson_reg_zeroinfl.md`) is made by the developer offline.
 
-## Creating the engine-specific `.md` files
+Take a look at the [actual file](https://github.com/tidymodels/parsnip/blob/main/R/poisson_reg_zeroinfl.R) if you want to see it all. 
+
+To summarize: the relationship between these `.R` files and the `.md` files that they include is:
+
+```
+:
+├── R
+│   ├── :
+│   ├── :
+│   ├── bag_tree.R.            <- model definition code that has the Sexprs
+│   ├── bag_tree_C5.0.R        <- wrapper around bag_tree_C5.0.md  (below)
+│   ├── bag_tree_rpart.R       <- wrapper around bag_tree_rpart.md (below)
+:   :
+:   :
+├── man
+│   ├── rmd
+│   │   ├──:
+│   │   ├── :
+│   │   ├── aaa.Rmd            <- sourced by all other Rmd files
+│   │   ├── :
+│   │   ├── :
+│   │   ├── bag_tree_C5.0.Rmd  <- engine details for the C5.0 engine only
+│   │   ├── bag_tree_C5.0.md
+│   │   ├── bag_tree_rpart.Rmd
+│   │   ├── bag_tree_rpart.md
+:   :   :
+```
+
+
+## Creating the engine-specific `.md` files for `.Rmd` files
 
 How do we make these markdown files? These are created by corresponding `.Rmd` files contained in `parsnip/man/rmd/`. There are `.Rmd` files for the engines defined in parsnip as well as the extension packages listed by `parsnip:::extensions()`.
 
 Each `.Rmd` file uses `parsnip/man/rmd/aaa.Rmd` as a child document. This file defines helper functions for the engine-specific documentation and loads some specific packages. 
 
 The `.Rmd` files use packages that are not formally parsnip dependencies (these are listed in `aaa.Rmd`). It also requires the parsnip extension packages defined in `parsnip:::extensions()`. 
 
-The `.Rmd` files have a consistent structure and there are numerous examples of these files in the package. The main sections are: 
+There is an internal helper function (`parsnip:::install_engine_packages()`) that will install the extension packages as well as a few others that are required to build all of the documentation files. 
+
+The `.Rmd` files have a consistent structure and there are [numerous examples](https://github.com/tidymodels/parsnip/tree/main/man/rmd) of these files in the package. The main sections are: 
 
  - The list of possible engines.
  - The list of tuning parameters, if any, and other arguments of interest. 
@@ -57,11 +104,15 @@ The `.Rmd` files have a consistent structure and there are numerous examples of
 
 To convert the `.Rmd` files to `.md`, use the function `knit_engine_docs()`. After this, use `devtools::document()` to create the engine specific `.Rd` files. 
 
+**Please** look at the output of the knitting; if there are errors, they will show up there. 
+
 To test the results, do a hard restart of the R session (i.e., do not use `load_all()`). 
 
 ## The main function `.Rd` files
 
-This type of file determines the engine-specific `.Rd` files for the model function and enumerates their values in a bulleted list. For example, `poisson_reg.R` has the line: 
+_This section has information that is probably only needed by the core developers._
+
+Recall that the `.Rd` files are created from the `.R` files. There are some fancy things that we do in the `.R` files to list the engines. For example, `poisson_reg.R` has the line: 
 
 ```r
 #' \Sexpr[stage=render,results=rd]{parsnip:::make_engine_list("poisson_reg")}
@@ -70,9 +121,10 @@ This type of file determines the engine-specific `.Rd` files for the model funct
 This finds the relevant engine `.Rd` files and creates the corresponding `.Rd` markup: 
 
 ```
-There are different ways to fit this model. The method of estimation is 
-chosen by setting the model \emph{engine}. The engine-specific pages  
-for this model are listed below.
+There are different ways to fit this model, and the method of estimation is  
+chosen by setting the model \emph{engine}. The engine-specific pages  for this 
+model are listed  below.
+
 
 \itemize{
   \item \code{\link[parsnip:details_poisson_reg_glm]{glm}¹²}
@@ -85,7 +137,7 @@ for this model are listed below.
   \item \code{\link[parsnip:details_poisson_reg_zeroinfl]{zeroinfl}²}
 }
 
-¹ The default engine. ² May require a parsnip extension package.
+¹ The default engine. ² Requires a parsnip extension package.
 ```
 
 There is a similar line at the bottom of the files that creates the _See Also_ list:
@@ -96,6 +148,8 @@ There is a similar line at the bottom of the files that creates the _See Also_ l
 
 ## Generating the model flat file
 
+_This is also for core developers_. 
+
 As previously mentioned, the parsnip package contains a file `models.tsv`. To create this file:
 
 1. Load the packages listed in `parsnip:::extensions()`.