Using an R Markdown Document as a source for functions

问题

I'm looking into R Markdown for documenting functions I regularly use. I will put them into an R Markdown file to document them and then be able to read my thinking behind the function if i come back to it months later

My question is, if i start a new R project, Is it possible to source the r markdown file and use the library of functions i have created just by calling them similarly to if i was sourcing a regular R file. I dont really wish to maintain two sets of function files

I appreciate this may be a beginners question but any help pointing to tutorials and the like would be greatly appreciated

Thanks

回答1:

As was mentioned in the comments, you should probably create a package for this purpose. But if you insist on putting function definitions in scripts and document them using RMarkdown files, using read_chunk() from the knitr package might be the way to go.

Note that this approach differs slightly from what you requested. You wanted to have the function definition in the markdown file together with the documentation. And then you wanted to somehow source that file into your R script in order to use the function. I did not find a way to do this (even though it might be possible).

The alternative that I propose puts the function definition in its own R script, say fun.R. The Rmarkdown file then reads the function definition from fun.R and adds documentation. If you want to use the function in some other script, you can simply source fun.R (and not the markdown file). This still means that you have to maintain the code for the function definition only once.

So let me show this with an example. This is fun.R:

## ---- fun
fun <- function(x) x^2

The first line is an identifier that will be used later. The markdown file is as follows:

---
title: "Documentation of fun()"
output: html_document
---

This documents the function `fun()` defined in `fun.R`.
```{r,cache = FALSE}
knitr::read_chunk("fun.R")
```

This is the function definition
```{r fun}
```

This is an example of how  to use `fun()`:
```{r use_fun}
fun(3)
```

The first chunk reads in fun.R using knitr::read_chunk. Later on, you can define an empty chunk that has the identifier that was used in fun.R as its name. This will act as if the contents of fun.R were written directly in this file. As you see, you can also use fun() in later chunks. This is a screenshot of the resulting html file:

In a script where you want to use fun() you simply add source("fun.R") to source the function definition.

You could also have several functions in a single R file and still document them separately. Simply put an identifier starting with ## ---- before each function definition and then create empty chunks referring to each one of the identifiers.

This is admittedly somewhat more complicated than what you asked for, because it involves two files instead of just one. But at least there is no redundancy

回答2:

Perhaps this is close enough -- you can use the github klmr/modules package (not the CRAN modules package) to combine roxygen2 documentation and code in a single file without creating a package. For example, after installing the modules package copy this to the clipboard and then paste it into the R console to create a single file module with embedded documentation. The subsequent code then imports it, runs a function from it and invokes help. See the documentation of the modules package for more info.

Note that this has the following advantages: (1) everything is in a single file, (2) if you later decide to move to using packages you can use the very same file in your package with roxygen2 -- no need to revise anything, (3) any learning of roxygen2 applies to packages too.

# create a file with our documentation and code

Lines <- "
#' Add two numbers.
#'
#' @param x the first number.
#' @param y the second number.
#' @return The sum.
#' @note This is just a simple example.
#'
#' This function is a simple example intended to show how to use the modules
#' package with roxygen2.
add2 <- function(x, y) x + y
"
cat(Lines, file = "test.R")


# now we can import it 
# devtools::install_github("klmr/modules")
library(modules)

test <- import("test")  # do not include the .R extension

test$add2(1, 2)
## [1] 3

# this will cause help page to appear
?test$add2

来源：https://stackoverflow.com/questions/35650785/using-an-r-markdown-document-as-a-source-for-functions

标签

r-markdown