documentation_workflow.md

In trenchproject/TrenchR: Tools for Microclimate and Biophysical Ecology

Documentation Workflow

We're using Rdpack and BiBTeX to manage citations in the documentation, which requires a little more work than a standard Roxygen documentation setup.

To include a citation

1. check if it is in inst/REFERENCES.bib

2. if not, create an entry it, save the bib file, and open a fresh R session (this is important, as Rdpack sets environments that prevent updating in one session)

3. wherever you would like to include the citation in the roxygen documentation use

  \insertCite{< citation key >}{TrenchR}

if you want it to be like Name (Year) instead of (Name Year), use

  \insertCite{< citation key >;textual}{TrenchR}

Other formatting, etc. is available, see https://github.com/GeoBosh/Rdpack.

1. then add the references section to the roxygen documentation

#'
#' @references
#'   \insertAllCited{}

1. build the documentation at the command line

devtools::document()

1. if you run a standard help look up ("?functionname"), you'll notice that the BibTex isn't actually rendered. To see it, you need to use viewRd:

Rdpack::viewRd("./man/<functionname>.Rd")

1. You can check to verify that the documentation will render fully properly by running

devtools::build()

and then installing the package from the built zip file and running

?TrenchR::functionname

ALL the Help Files

To generate all of the help files in one line of code, run

mapply(Rdpack::viewRd, paste0("./man/", list.files("./man")[grepl(".Rd", list.files("./man"))]))

trenchproject/TrenchR documentation built on Oct. 10, 2023, 10:12 p.m.