Skip to content

Commit b1e2577

Browse files
coatlesscoatless
committed
Add README.Rmd
1 parent fb10df5 commit b1e2577

File tree

2 files changed

+217
-41
lines changed

2 files changed

+217
-41
lines changed

‎README.Rmd

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
output: github_document
3+
---
4+
5+
<!-- README.md is generated from README.Rmd. Please edit that file -->
6+
7+
```{r, include = FALSE}
8+
knitr::opts_chunk$set(
9+
collapse = TRUE,
10+
comment = "#>"
11+
)
12+
```
13+
14+
# rocleteer
15+
16+
<!-- badges: start -->
17+
[![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)
18+
<!-- badges: end -->
19+
20+
A roxygen2 extension collection package.
21+
22+
## Installation
23+
24+
You can install the development version of `{rocleteer}` from GitHub:
25+
26+
```r
27+
# install.packages("devtools")
28+
devtools::install_github("coatless-rpkg/rocleteer")
29+
```
30+
31+
## Usage
32+
33+
In your package's `DESCRIPTION` file, add `{rocleteer}` to your Suggests and
34+
`coatless-rpkg/rocleteer` to your Remotes:
35+
36+
```
37+
Suggests:
38+
rocleteer
39+
40+
Remotes:
41+
coatless-rpkg/rocleteer
42+
43+
Roxygen: Roxygen: list(..., packages = c("rocleteer"))
44+
```
45+
46+
where `...` could be `roclets = c("collate", "namespace", "rd")`.
47+
48+
### `@examplesTempdir`
49+
50+
When writing examples for R package functions, you often need to create
51+
temporary files or directories. To avoid cluttering the user's workspace, it's
52+
good practice to use a temporary directory for these examples.
53+
54+
Traditionally, you would need to manually set up and switch out of the temporary
55+
directory like this:
56+
57+
```r
58+
#' @examples
59+
#' \dontshow{.old_wd <- setwd(tempdir())}
60+
#'
61+
#' # Your code here
62+
#'
63+
#' \dontshow{setwd(.old_wd)}
64+
```
65+
66+
With `{rocleteer}`, you can simply use the `@examplesTempdir` tag instead:
67+
68+
```r
69+
#' @examplesTempdir
70+
#' # Your code here
71+
```
72+
73+
The `@examplesTempdir` tag handles this automatically. So, if you have a function
74+
like this:
75+
76+
```r
77+
#' Example function
78+
#'
79+
#' @examplesTempdir
80+
#' # This code will run in a temporary directory
81+
#' write.csv(mtcars, "mtcars.csv")
82+
#' read.csv("mtcars.csv")
83+
#' file.remove("mtcars.csv")
84+
#'
85+
#' @export
86+
example_function <- function() {
87+
# Function implementation
88+
}
89+
```
90+
91+
The documentation will be processed by roxygen2 as:
92+
93+
```r
94+
#' Example function
95+
#'
96+
#' @examples
97+
#' \dontshow{
98+
#' .old_wd <- setwd(tempdir()) # examplesTempdir
99+
#' }
100+
#' # This code will run in a temporary directory
101+
#' write.csv(mtcars, "mtcars.csv")
102+
#' read.csv("mtcars.csv")
103+
#' file.remove("mtcars.csv")
104+
#'
105+
#' \dontshow{
106+
#' setwd(.old_wd) # examplesTempdir
107+
#' }
108+
#'
109+
#' @export
110+
example_function <- function() {
111+
# Function implementation
112+
}
113+
```
114+
115+
116+
> [!NOTE]
117+
>
118+
> 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.
119+
120+
## License
121+
122+
AGPL (>=3)

‎README.md

Lines changed: 95 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,114 @@
1-
# r-pkg
21

3-
This repository houses a devcontainer that setups an R package development environment. The container is setup to work with [GitHub Codespaces](https://github.com/features/codespaces) to instantly have a cloud-based developer workflow.
2+
<!-- README.md is generated from README.Rmd. Please edit that file -->
43

5-
You can try out the Codespace by clicking on the following button:
4+
# rocleteer
65

7-
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/coatless-devcontainer/r-pkg?quickstart=1)
6+
<!-- badges: start -->
87

9-
> [!NOTE]
10-
>
11-
> Codespaces are available to Students and Teachers for free [up to 180 core hours per month](https://docs.github.com/en/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom#about-github-codespaces)
12-
> through [GitHub Education](https://education.github.com/). Otherwise, you will have
13-
> [up to 60 core hours and 15 GB free per month](https://github.com/features/codespaces#pricing).
14-
15-
Or, you can press the template button to create a new repository with the same setup so that you
16-
can work locally on the devcontainer:
8+
[![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)
9+
<!-- badges: end -->
1710

18-
[![Use this template](https://img.shields.io/badge/Use%20this%20template-Create%20new%20repository-blue?logo=github)](https://github.com/coatless-devcontainer/r-pkg/generate)
11+
A roxygen2 extension collection package.
1912

20-
This will create a fork of the repository that can be worked on inside a local copy of
21-
[Visual Studio Code](https://code.visualstudio.com/) through the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). With the extension installed, you can open the repository in a container by pressing `F1` (to bring up command palette) and typing `Dev Container: Reopen in Container`.
13+
## Installation
2214

23-
Lastly, you can directly obtain the underlying container image by typing in Terminal:
15+
You can install the development version of `{rocleteer}` from GitHub:
2416

25-
```sh
26-
docker pull ghcr.io/coatless-devcontainer/r-pkg:latest
17+
``` r
18+
# install.packages("devtools")
19+
devtools::install_github("coatless-rpkg/rocleteer")
2720
```
2821

29-
## Quick start
22+
## Usage
3023

31-
Run the following series of commands inside of R once the container opens. Make sure to change `"name-of-package"` to your current package name.
24+
In your package’s `DESCRIPTION` file, add `{rocleteer}` to your Suggests
25+
and `coatless-rpkg/rocleteer` to your Remotes:
3226

33-
```r
34-
usethis::create_package("name-of-package")
35-
usethis::use_package_doc()
36-
usethis::use_agpl3_license()
37-
usethis::use_testthat()
38-
usethis::use_github_action("check-standard")
39-
usethis::use_pkgdown_github_pages()
40-
```
27+
Suggests:
28+
rocleteer
29+
30+
Remotes:
31+
coatless-rpkg/rocleteer
4132

42-
## Resources
33+
Roxygen: Roxygen: list(..., packages = c("rocleteer"))
4334

44-
- [Manual: Writing R extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html)
45-
- [Textbook: R Packages](https://r-pkgs.org/)
46-
- [usethis](https://usethis.r-lib.org/)
47-
- [devtools](https://devtools.r-lib.org/)
35+
where `...` could be `roclets = c("collate", "namespace", "rd")`.
4836

49-
## Developer notes
37+
### `@examplesTempdir`
5038

51-
This repository uses a pre-built container strategy to have GitHub Actions build and, then, store the devcontainer in [GitHub's Container Repository](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).
39+
When writing examples for R package functions, you often need to create
40+
temporary files or directories. To avoid cluttering the user’s
41+
workspace, it’s good practice to use a temporary directory for these
42+
examples.
5243

53-
We place the main logic of the devcontainer in [`.github/.devcontainer/devcontainer.json`](https://github.com/coatless-devcontainer/r-pkg/blob/main/.github/.devcontainer/devcontainer.json). From there, we use [`.github/workflows/pre-build-devcontainer.yml`](https://github.com/coatless-devcontainer/r-pkg/blob/main/.github/workflows/pre-build-devcontainer.yml) to build and publish the devcontainer onto GitHub's Container repository for the organization. Then, the repository's [`.devcontainer/devcontainer.json`](https://github.com/coatless-devcontainer/r-pkg/blob/main/.devcontainer/devcontainer.json) pulls the pre-built image.
44+
Traditionally, you would need to manually set up and switch out of the
45+
temporary directory like this:
5446

55-
> [!IMPORTANT]
47+
``` r
48+
#' @examples
49+
#' \dontshow{.old_wd <- setwd(tempdir())}
50+
#'
51+
#' # Your code here
52+
#'
53+
#' \dontshow{setwd(.old_wd)}
54+
```
55+
56+
With `{rocleteer}`, you can simply use the `@examplesTempdir` tag
57+
instead:
58+
59+
``` r
60+
#' @examplesTempdir
61+
#' # Your code here
62+
```
63+
64+
The `@examplesTempdir` tag handles this automatically. So, if you have a
65+
function like this:
66+
67+
``` r
68+
#' Example function
69+
#'
70+
#' @examplesTempdir
71+
#' # This code will run in a temporary directory
72+
#' write.csv(mtcars, "mtcars.csv")
73+
#' read.csv("mtcars.csv")
74+
#' file.remove("mtcars.csv")
75+
#'
76+
#' @export
77+
example_function <- function() {
78+
# Function implementation
79+
}
80+
```
81+
82+
The documentation will be processed by roxygen2 as:
83+
84+
``` r
85+
#' Example function
86+
#'
87+
#' @examples
88+
#' \dontshow{
89+
#' .old_wd <- setwd(tempdir()) # examplesTempdir
90+
#' }
91+
#' # This code will run in a temporary directory
92+
#' write.csv(mtcars, "mtcars.csv")
93+
#' read.csv("mtcars.csv")
94+
#' file.remove("mtcars.csv")
95+
#'
96+
#' \dontshow{
97+
#' setwd(.old_wd) # examplesTempdir
98+
#' }
99+
#'
100+
#' @export
101+
example_function <- function() {
102+
# Function implementation
103+
}
104+
```
105+
106+
> \[!NOTE\]
56107
>
57-
> Make sure to specify the permissions as stated in the GitHub Actions workflow linked above
58-
> and for organizations please make sure to have the organization's container registry enabled.
59-
>
60-
> For more information, see [GitHub's Container Registry documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).
108+
> This roclet is inspired by [an old post of
109+
> mine](https://blog.thecoatlessprofessor.com/programming/r/hiding-tempdir-and-tempfile-statements-in-r-documentation/)
110+
> that I initially shared in 2018 covering this pattern.
111+
112+
## License
113+
114+
AGPL (\>=3)

0 commit comments

Comments
 (0)