move engine help documentation to a side package

[topepo]

The dynamic documentation for parsnip is setup so that there are specific help pages for each model/engine combinations. These have technical details and parsnip only loads the pages for packages that are loaded. For example, the engines for Poisson regression are only shown if the poissonreg package is loaded.

The pros of this:

• More in-depth help
• Modular help does not overwhelm users with information.

The cons:

• There are hidden package dependencies that users need to have installed to build the docs (even if a PR is to fix a typo). This can include engine specific dependencies.
• The documentation can take a while to compile.
• The use of @includeRmd can lead to the annihilation of the namespace file if there is an error building the docs.
• Extension packages have their own doc files

Proposal:

Create a separate package that contains all of the engine-specific documentation files (parsnip and extension packages). When a model help file is opened, the same (or similar) engine list is shown but the links are to the documentation package pages.

The pros of this:

• Same as above
• All documentation is in one place
• Contributors to parsnip do not have to deal with building the docs
• Better formalization of documentation functions.
• Simpler, more robust code to create links.
• Less code in parsnip, far fewer R and Rd files.
• Users can find out about new extension packages without having them loaded.

Cons:

• Even more packages required to compile docs.
• Docs can get out of synch with parsnip.
• Possible confusion with having some help files in a different package (or pkgdown site).

[topepo]

After discussion the tidyverse group meeting, a separate package is probably not optimal.

The second approach would be to decouple compiling the engine Rmd files from devtools::document() by importing pre-rendered md files. An exported function to knit them can be included generate the md from the engine Rmd files.

Some additional things that we can do:

• As previously proposed, include the extension package engine files in parsnip. If we compile their files outside of document(), these would be done by the developers (or contributors) as needed. This means that we can have additional, informal dependencies that are required for the extension packages.

• The current docs are dynamic; they show engines for all loaded packages. If we include all of the extension package engine docs, we can make this static and call out what packages are required to get access to specific engines. We could have a function to populate the engine lists.

• If the engine lists are static, it would make sense to have a new GHA on a chron job to knit the rd files and populate the engine lists in the Rd files (and commit them). The additional package requirements can be listed in the description file (Config/Needs/documentation) and handled by GHA.

[juliasilge]

Closed in #631

[github-actions]

This issue has been automatically locked. If you believe you have found a related problem, please file a new issue (with a reprex: https://reprex.tidyverse.org) and link to this issue.