[Review]: create_template documentation II

[Schiano-NOAA]

Directions

Please comment on the follow topics regarding documentation of the function create_template:

• Arguments (model_results through "..." )
• Value
• Examples

Think about the perspective of both new and advanced users when reviewing the documentation.

You can access the documentation quickly and easily by running ?asar::create_template in your console. Remember to only focus on the documentation. If you have any feedback regarding the process of create_template, please leave a separate issue.

[BenWilliams-NOAA]

Suggested edits below:

#' @param model_results Path to an `.rda` file containing model output  
#'   processed via `stockplotr::convert_output()', default: 'NULL'.  
#' @param tables_dir Path to directory containing table files. Defaults to working directory.  
#' @param figures_dir Path to directory containing figure files. Defaults to working directory.  
#' @param spp_image Path to a custom species image. If empty, searches `asar` 
#'   resources for a matching species name.  
#' @param bib_file Path to bibliography file (`.bib`). Defaults to `asar_references.bib` in the working directory.
#' @param new_template Logical. If `TRUE` (default), creates a fresh skeleton. 
#'   If `FALSE`, attempts to pull the last saved version.
#' @param rerender_skeleton Logical. If `TRUE`, updates the `skeleton.qmd` 
#'   YAML and structure while preserving existing `.qmd` section files. Default `FALSE`
#' @param custom Default `FALSE`,  if `TRUE`, allows for non-standard sectioning rather than the default for stock assessments in
#'  the region.
#' @param custom_sections List of existing sections to include in
#' the custom template. Note: this only includes sections within
#'  list.files(system.file("templates", "skeleton",
#'  package = "asar")). The name of the section, rather than the
#'  name of the file, can be used (e.g., 'abstract' rather than
#'  '00_abstract.qmd'). If adding a new section, also use
#'   parameters 'new_section' and 'section_location'.
#' @param new_section Names of section(s) (e.g., introduction, results) or
#' subsection(s) (e.g., a section within the introduction) that will be
#' added to the document. Please make a short list if >1 section/subsection
#' will be added. The template will be created as a quarto document, added
#' into the skeleton, and saved for reference. Default NULL.
#' @param section_location Where new section(s)/subsection(s) will be added to
#' the skeleton template. Please use the notation of 'placement-section'.
#' For example, 'in-introduction' signifies that the new content would
#' be created as a child document and added into the 02_introduction.qmd.
#' To add >1 (sub)section, make the location a list corresponding to the
#' order of (sub)section names listed in the 'new_section' parameter.
#' @param parameters Default `TRUE`. Whether to include Quarto parameters in the YAML.
#' @param param_names, List of additional custom parameters to 
#'   include in the report metadata. Default `NULL`
#' @param param_values List of values associated with the order
#'  of parameter names. Parameters automatically included:
#'  office, region, species (each of which are listed as
#'  individual parameters for this function, above). Default `NULL`
#' @param ... Additional arguments passed to internal helper functions like 
#'   `create_citation()` or `create_yaml()`.
#'
#' @return Invisibly returns the path to the created `report/` directory. 
#'   Side effects include the creation of a directory structure, `.qmd` files, 
#'   and support files (images, `.bib`, `.tex`).
#'
#' @details 
#' The function creates a `report/` subdirectory within `file_dir`. The 
#' primary file is a "skeleton" Quarto document that calls various sections 
#' as child documents. Users should edit the individual section `.qmd` files 
#' rather than the main skeleton whenever possible.
#'
#' @export

I get the sense that the custom section will prove overly complex and only used by very few folks (hopefully i'm wrong on that!)

Note 1: spp_image = "" should more appropriately be spp_image = NULL
Note 2: Could do away with custom and simply have if (!is.null(custom_sections))
Note 3: The param_names and param_values could be more easily brought in using a named list. The names(list)[[1]] and list[[1]] can be used to populate the fields in the doc