---
title: "An Introduction to *document*"
author: "Andreas Dominik Cullmann"
date: 2022-08-17, 09:21:00
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{An Introduction to document}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# 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

 - create function documentation with roxygen2 
 - detect code/documentation mismatches  
 - save the documentation to disk
 - view the documentation in your interactive R session

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
```{r, comment = ""}
path <- system.file("files", "minimal.R", package = "document")
cat(readLines(path), sep = "\n")
```
Then
```{r, result = "hide", message = FALSE}
d <- document::document(file_name = path, check_package = FALSE)
```
creates a
Portable Document Format 
[(pdf)](https://en.wikipedia.org/wiki/Portable_Document_Format) file,
an Hypertext Markup Language
[(html)](https://en.wikipedia.org/wiki/HTML) file and a 
[plain text](https://en.wikipedia.org/wiki/Plain_text) file.
The plain text reads
```{r, comment = ""}
cat(readLines(d[["txt_path"]]), sep = "\n")
```

You can view a copy of the html file 
[here](http://htmlpreview.github.io/?https://github.com/fvafrCU/document/blob/master/inst/tests/files/minimal.html). 
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

```{r, comment = ""}
path <- system.file("files", "simple.R", package = "document")
cat(readLines(path), sep = "\n")
```
Then you can write documentation using:
```{r, result = "hide", message = FALSE}
d <- document::document(file_name = path, check_package = FALSE)
```
```{r, comment = ""}
cat(readLines(d[["txt_path"]]), sep = "\n")
```

# Displaying Temporary Help Files
```{r, echo = FALSE}
# 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
```{r, comment = "", message = FALSE, warning = FALSE}
path <- system.file("files", "minimal.R", package = "document")
document::man(x = path, topic = "foo")
```