README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# rocleteer

<!-- badges: start -->
[![R-CMD-check](https://github.com/coatless-rpkg/rocleteer/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-rpkg/rocleteer/actions/workflows/R-CMD-check.yaml)![Active](https://img.shields.io/badge/Status-Active-green)![Experimental](https://img.shields.io/badge/Status-Experimental-blue)
<!-- badges: end -->

A roxygen2 extension collection package.

## Installation

You can install the development version of `{rocleteer}` from GitHub:

```r
# install.packages("devtools")
devtools::install_github("coatless-rpkg/rocleteer")
```

## Usage

In your package's `DESCRIPTION` file, add `{rocleteer}` to your Suggests,
`coatless-rpkg/rocleteer` to your Remotes, and include `rocletter` in your
Roxygen `list` of packages.

```
Suggests:
    rocleteer

Remotes:
  coatless-rpkg/rocleteer

Roxygen: list(..., packages = c("rocleteer"))
```

where `...` could be `roclets = c("collate", "namespace", "rd")`.

### `@examplesTempdir`

When writing examples for R package functions, you often need to create
temporary files or directories. To avoid cluttering the user's workspace, it's 
good practice to use a temporary directory for these examples.

Traditionally, you would need to manually set up and switch out of the temporary
directory like this:

```r
#' @examples
#' \dontshow{.old_wd <- setwd(tempdir())}
#'
#' # Your code here
#'
#' \dontshow{setwd(.old_wd)}
```

With `{rocleteer}`, you can simply use the `@examplesTempdir` tag instead:

```r
#' @examplesTempdir
#' # Your code here
```

The `@examplesTempdir` tag handles this automatically. So, if you have a function
like this:

```r
#' Example function
#'
#' @examplesTempdir
#' # This code will run in a temporary directory
#' write.csv(mtcars, "mtcars.csv")
#' read.csv("mtcars.csv")
#' file.remove("mtcars.csv")
#'
#' @export
example_function <- function() {
  # Function implementation
}
```

The documentation will be processed by roxygen2 as:

```r
#' Example function
#'
#' @examples
#' \dontshow{
#' .old_wd <- setwd(tempdir()) # examplesTempdir
#' }
#' # This code will run in a temporary directory
#' write.csv(mtcars, "mtcars.csv")
#' read.csv("mtcars.csv")
#' file.remove("mtcars.csv")
#'
#' \dontshow{
#' setwd(.old_wd) # examplesTempdir
#' }
#'
#' @export
example_function <- function() {
  # Function implementation
}
```


> [!NOTE]
>
> This roclet is inspired by [an old post of mine](https://blog.thecoatlessprofessor.com/programming/r/hiding-tempdir-and-tempfile-statements-in-r-documentation/) that I initially shared in 2018 covering this pattern. 

## License

AGPL (>=3)