Document a Single R Code File

Description

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::roxygenize on (chunks of) a single code file.
This package enables you to

1. create function documentation with roxygen2

2. detect code/documentation mismatches

3. save the documentation to disk

4. view the documentation in your interactive R session

You will probably be looking for document and man, the remaining functions are mainly for internal use.

Details

R is a programming language that supports and checks documentation for program libraries (called ‘packages’). The package roxygen2 provides a tool for creating documentation from annotated source code - much like doxygen, javadoc and docstrings/pydoc do.

And R is a free software environment for statistical computing and graphics, used by people like me who start out hacking down code, eventually pouring chunks of code into functions (and sometimes even ending up creating and documenting packages). Along that work flow you cannot use R's documentation system, let alone roxygen2, unless you have come to forge your code into a package.

I am fully aware of the fact that roxygen2 is meant to document packages, not single code chunks. So should you. Nevertheless I feel the temptation to use roxygen2-style comments in code chunks that are not part of any package. And to convert them to pdf for better readability.

Warning

This package writes to disk, so never run as superuser.

Note

This package is basically a wrapper to

1. roxygen2. It internally creates a temporary package from the code file provided (using utils::package.skeleton) which it then passes to roxygen2::roxygenize.

2. R CMD commands run by callr.

Author(s)

Maintainer: Andreas Dominik Cullmann fvafrcu@mailbox.org

See Also

docstring (https://cran.r-project.org/package=docstring) also creates temporary help pages as well but using a different technical approach (allowing you to view them in the RStudio help pane). But it creates them from python style docstring-like comments it then parses into roxygen2. And it does not write to file so far.

Clean a String Created From a Run Through RUnit

Description

Why am I doing this? It want to run RUnit tests from within R CMD check check and interactively. Files produced are compared with expected files. Now R CMD check and interactive (and batch) runs of RUnit give different encodings. I don't know why, but they do. And this is a rather lousy fix. See the code for details.

Usage

Rd_txt_RUnit(txt)

Arguments

Value

The sanitized character vector.

Alter Contents of a DESCRIPTION File

Description

Substitutes and/or adds fields in a DESCRIPTION file.

Usage

alter_description_file(path, substitution = NULL, addition = NULL)

Arguments

Value

value of write.dcf.

Note

Adding NULL elements (Title = NULL, for example) to substitution does not delete or overwrite the entry in the DESCRIPTION file.
alter_description_file() is deprecated, please use CRAN package desc.

Run R CMD check on a Package Directory

Description

This is a wrapper to rcmdcheck::rcmdcheck, signaling notes, warnings and errors.

Usage

check_package(
  package_directory,
  working_directory,
  check_as_cran = TRUE,
  stop_on_check_not_passing = FALSE,
  debug = TRUE
)

Arguments

Value

The return value of rcmdcheck::rcmdcheck.

Get Warnings or Notes From rcmdcheck

Description

rcmdcheck returns a list containing characters that give errors, warnings and notes.

Usage

checks(rcmdcheck_value)

Arguments

Details

Use ! any(checks(x))) to ensure there were no errors, warnings or notes in x.

Value

A named logical vector, all FALSE if there were no errors, warnings or notes.

Make a Default DESCRIPTION File Pass R CMD check

Description

utils::package.skeleton leaves us with a DESCRIPTION that throws a warning in R CMD check. Fix that.

Usage

clean_description_file(path)

Arguments

Value

Invisibly NULL.

Display the Contents of an R Documentation File

Description

This is meant for internal use by man.

Usage

display_Rd(rd_file)

Arguments

Value

The return value of removing the temporary file.

Note

The Contents are converted to text with Rdconv and then saved to a temporary file which is then displayed using the R pager. Using cat on the text would not allow for using different pagers.

Document (Chunks of) an R Code File

Description

Document (Chunks of) an R Code File

Usage

document(
  file_name,
  working_directory = NULL,
  output_directory = tempdir(),
  dependencies = NULL,
  sanitize_Rd = TRUE,
  runit = FALSE,
  check_package = TRUE,
  check_as_cran = check_package,
  stop_on_check_not_passing = check_package,
  clean = FALSE,
  debug = TRUE,
  ...
)

Arguments

Value

A list containing

pdf_path

The path to the pdf file produced,

txt_path

The path to the text file produced,

html_path

The path to the html file produced,

check_result

The return value of rcmdcheck::rcmdcheck()

Note

One of the main features of R CMD check is checking for code/documentation mismatches (it behaves pretty much like doxygen). No build system can check whether your documentation is useful, but R CMD check checks if it is formally matching your code. This check is the basic idea behind document. The possibility to disable the R CMD check is there to disable CPU consuming checks while testing the package. Stick with the default! And do not forget to export your functions using the line
#' @export
should you provide examples.

Examples

res <- document(file_name = system.file("files", "minimal.R",
                                        package = "document"),
                check_package = FALSE) # this is for the sake of CRAN cpu
                # time only. _Always_ stick with the default!

# View R CMD check results. If we had set check_package to TRUE in the above
# example, we now could retrieve the check results via:
cat(res[["check_result"]][["output"]][["stdout"]], sep = "\n")
cat(res[["check_result"]][["output"]][["stderr"]], sep = "\n")

# Copy docmentation to current working directory.
# This writes to your disk, so it's disabled.
# Remove or comment out the next line to enable.
if (FALSE)
    file.copy(res[["pdf_path"]], getwd())

Fake a Package From a Single Code File

Description

To build documentation for a single code file, we need a temporary package. Of course the code file should contain roxygen2 comments.

Usage

fake_package(file_name, working_directory = NULL, dependencies = NULL, ...)

Arguments

Value

A string containing the path to the faked package.

A Convenience Wrapper

Description

Just a wrapper to getOption("document_package_directory")

Usage

get_dpd()

Value

getOption("document_package_directory")

Check Whether a File is Probably an R Documentation File

Description

This is meant for internal use by man.

Usage

is_Rd_file(x)

Arguments

Value

TRUE if the file is probably an R documentation file, FALSE otherwise.

Note

The check might produce false negatives (erroneously assuming the file is not an R documentation file).

Display a Help Page From a File's Documentation

Description

Display a help-like page from an existing R documentation (*.Rd) file, a topic from a temporary package with options("document_package_directory") set or a topic from an R code file containing roxygen2 documentation.

Usage

man(x, topic = NA, force_Rd = FALSE)

Arguments

Value

Invisibly the status of display_Rd.

Examples

document::document(file_name = system.file("files", "minimal.R",
                   package = "document"), check_package = FALSE)
document::man("foo")
# this equivalent to
path <- system.file("files", "minimal.R", package = "document")
document::man(x = path, topic = "foo")

Sort a Character Vector in Lexical Order Avoiding the Locale

Description

sort uses the collation of the locale (see Comparison), which results in different sorting. If a (RUnit) check relies on sorting, we need to avoid the locale.

Usage

sort_unlocale(char)

Arguments

Value

The sorted character vector.

Throw an Error

Description

Throws a condition of class c("document", "error", "condition").

Usage

throw(message_string, system_call = sys.call(-1), ...)

Arguments

Details

We use this condition as an error dedicated to document.

Value

FALSE. But it does not return anything, it stops with a condition of class c("document", "error", "condition").

Return the Usage of a Function From Within the Function

Description

Get a usage template for a function from within the function. If you encounter misguided usage, you can display the template.

Usage

usage(n = -1, usage = FALSE)

Arguments

Value

A character string giving the Usage as help would do.

Examples

# usage with assignment operator:
foo <- function(x) {
    u <- usage()
    message("Usage is: ", u)
}
foo()

# usage without assignment operator:
bar <- function(x) {
    message(usage(n = -2))
}
bar()

Throw a Warning

Description

Throws a condition of class c("document", "warning", "condition").

Usage

warn(message_string, system_call = sys.call(-1), ...)

Arguments

Details

We use this condition as a warning dedicated to document.

Value

The condition.

Write Documentation to Disk

Description

Read R documentation files from a package's source, convert and write them to disk.

Usage

write_the_docs(
  package_directory,
  file_name = package_directory,
  output_directory = tempdir(),
  dependencies = NULL,
  sanitize_Rd = TRUE,
  runit = FALSE
)

Arguments

Details

file_name will usually be provided by document as the R code file's name. This may, differing from a (temporary) package's name, contain underscores. If you use the functions directly: stick with the default, in which case internally the basename of your package_directory will be used. This should be a good guess.

Value

A list containing

pdf_path

The path to the pdf file produced.

txt_path

The path to the text file produced.

html_path

The path to the html file produced.