An Introduction to *document*

Teaser

Have you ever been tempted to create roxygen2-style documentation comments for one of your functions that was not part of one of your packages (yet)?

This is exactly what this package is about: running roxygen2 on (chunks of) a single code file.

Features

This package enables you to

It does so by creating a temporary package from (the chunks of) your single code file. It runs R CMD check to see if your code and documentation match. For the sake of cpu time on CRAN, I have disabled that check in all examples below by setting check_package = FALSE. You should always stick with the default. This is what this package is about!

Writing Documentation Files to Disk

A Minimal Example

Suppose you have a script

path <- system.file("files", "minimal.R", package = "document")
cat(readLines(path), sep = "\n")

Then

d <- document::document(file_name = path, check_package = FALSE)

creates a Portable Document Format (pdf) file, an Hypertext Markup Language (html) file and a plain text file. The plain text reads

cat(readLines(d[["txt_path"]]), sep = "\n")

You can view a copy of the html file here. The pdf file resembles a package's documentation pdf file.

Checking the code with R CMD check

By default, document checks the temporary package it creates from your code file using R CMD check. The corresponding call would be:

res <- document(file_name = system.file("files", "minimal.R",
                                        package = "document"),
                check_package = TRUE)

After that you could display the check results with:

cat(res[["check_result"]][["output"]][["stdout"]], sep = "\n")
cat(res[["check_result"]][["output"]][["stderr"]], sep = "\n")

A Simple Example

Suppose you have a script

path <- system.file("files", "simple.R", package = "document")
cat(readLines(path), sep = "\n")

Then you can write documentation using:

d <- document::document(file_name = path, check_package = FALSE)
cat(readLines(d[["txt_path"]]), sep = "\n")

Displaying Temporary Help Files

# owing to Dason Kurkiewicz <dasonk@gmail.com>,
# https://github.com/Dasonk/docstring
# This is only needed for the vignette, you can skip the setting of the option
# in regular use.
pager_function <- function(x, ...) {
    x <- readLines(x)
    x <- gsub("_", "", x)
    cat(paste(x, collapse = "\n"), "\n")
}
options(pager = pager_function)

You can display the help page for one of the documented functions using

path <- system.file("files", "minimal.R", package = "document")
document::man(x = path, topic = "foo")


Try the document package in your browser

Any scripts or data that you put into this service are public.

document documentation built on Aug. 19, 2022, 5:23 p.m.