You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
notice<- c(paste0("This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as ",
#' Opinionated set of files and folders to be excluded from linting, relative to the package path. To be used with [lint_rmd()], [lintr::lint_dir()] or
1223
-
#' [lintr::lint_package()].
1218
+
#' Returns an opinionated set of files and folders to be excluded from linting, relative to the root of the package directory. To be used with [lint_rmd()],
1219
+
#' [lintr::lint_dir()] or [lintr::lint_package()].
1224
1220
#'
1225
-
#' @param excl_vignettes Whether or not to exclude all `.Rmd` files under `vignettes/`. A logical scalar.
1221
+
#' @param excl_inst Whether or not to exclude all files under `inst/`. A logical scalar.
1222
+
#' @param excl_vignettes Whether or not to exclude all files under `vignettes/`. A logical scalar.
1226
1223
#'
1227
1224
#' @return A named list of [lintr::linters].
1228
1225
#' @seealso [`default_linters`][default_linters] and [lint_rmd()]
pkgpurl facilitates R package authoring using a literate programming approach. The main idea behind this is to write all of the R source code in R Markdown files (`Rmd/*.Rmd`), which allows the actual code to be freely mixed with explanatory and supplementary information in expressive Markdown format. The main object of pkgpurl is to provide a standardized way to compile the bare `.R` files from the prose-enhanced and thus more human-oriented`.Rmd` files.
7
+
pkgpurl facilitates R package authoring using a literate programming workflow. It enables you to write all R source code in R Markdown files, letting executable code coexist naturally with narrative explanations and supplementary context in expressive Markdown format. The primary purpose of pkgpurl is to provide a standardized way to compile the bare `.R` files from the richer, prose-enhanced `.Rmd` files.
8
8
9
-
The basic idea behind the concept this package implements originates from Yihui Xie. See his blog post [*Write An R Package Using Literate Programming Techniques*](https://yihui.org/rlp/) for more details, it’s definitively worth reading. This package’s function [`pkgpurl::purl_rmd()`](https://pkgpurl.rpkg.dev/dev/reference/purl_rmd.html) is just a less cumbersome alternative to the Makefile approach outlined by him.
9
+
The basic idea behind the concept this package implements originates from Yihui Xie. See his blog post [*Write An R Package Using Literate Programming Techniques*](https://yihui.org/rlp/) for more details, it’s definitively worth reading. This package’s function [`pkgpurl::purl_rmd()`](https://pkgpurl.rpkg.dev/reference/purl_rmd.html) is just a less cumbersome alternative to the Makefile approach outlined by him that offers additional convenience features like [auto-generating the pkgdown `Reference:` index](https://pkgpurl.rpkg.dev/reference/) or adding [copyright](https://pkgpurl.rpkg.dev/reference/purl_rmd.html#arg-add-copyright-notice) or [license](https://pkgpurl.rpkg.dev/reference/purl_rmd.html#arg-add-license-notice) notices.
10
+
11
+
Setting up a new project to write an R package in the R Markdown format differs slightly from the classic approach. [`pkgpurl::create_pkg()`](https://pkgpurl.rpkg.dev/reference/create_pkg.html) is offered as a convenience function similar to [`usethis::create_package()`](https://usethis.r-lib.org/reference/create_package.html) to populate a directory with all the files necessary for a new package in the R Markdown format.
10
12
11
13
## Pros and cons
12
14
@@ -50,7 +52,7 @@ The relevant editor options which adjust the canonical Markdown generation can e
50
52
</details>
51
53
<details>
52
54
<summary>
53
-
👍 <strong>All your code in a single, well-structured file</strong>
55
+
👍 <strong>All your main R code in a single, well-structured file</strong>
54
56
</summary>
55
57
56
58
The [traditional recommendation](https://style.tidyverse.org/package-files.html) to not lose overview of your package’s R source code is to split it over multiple files. The popular (and very useful) book *R Packages*[gives the following advice](https://r-pkgs.org/code.html#sec-code-organising):
@@ -59,9 +61,9 @@ The [traditional recommendation](https://style.tidyverse.org/package-files.html)
59
61
60
62
I think this is just ridiculous.
61
63
62
-
Instead, I encourage you to keep all your code (as far as possible) in a single file `Rmd/PACKAGE_NAME.Rmd` and structure it according to the [rules described here](https://pkgpurl.rpkg.dev/dev/reference/gen_pkgdown_ref.html#details), which even allows the [pkgdown `Reference:` index](https://pkgdown.r-lib.org/reference/build_reference.html#reference-index) to be automatically in sync with the source code structure. As a result, you re-organize (and thus most likely improve) your package’s code structure whenever you intend to improve the pkgdown reference – and vice versa. For a basic example, see [this very package’s main source file](https://gitlab.com/rpkg.dev/pkgpurl/-/blob/master/Rmd/pkgpurl.Rmd?plain=0).
64
+
Instead, I encourage you to keep all your code (as far as possible) in a single file `Rmd/PACKAGE_NAME.Rmd` and structure it according to the [rules described here](https://pkgpurl.rpkg.dev/reference/gen_pkgdown_ref.html#details), which even allows the [pkgdown `Reference:` index](https://pkgdown.r-lib.org/reference/build_reference.html#reference-index) to be automatically in sync with the source code structure. As a result, you re-organize (and thus most likely improve) your package’s code structure whenever you intend to improve the pkgdown reference – and vice versa. For a basic example, see [this very package’s main source file](https://gitlab.com/rpkg.dev/pkgpurl/-/blob/master/Rmd/pkgpurl.Rmd?plain=0).
63
65
64
-
Keeping all code in a single file frees you from the traditional hassle of finding a viable (but in the end still unsatisfactory) way to organize your R source code across multiple files. Of course, there are still good reasons to outsource code into separate files *in certain situations*, which nothing is stopping you from doing. You can also [exclude whole `.Rmd` files from purling using the `.nopurl.Rmd` filename suffix](https://pkgpurl.rpkg.dev/dev/reference/purl_rmd.html#-rmd-files-excluded-from-purling).
66
+
Keeping all code in a single file frees you from the traditional hassle of finding a viable (but in the end still unsatisfactory) way to organize your R source code across multiple files. Of course, there are still good reasons to outsource code into separate files *in certain situations*, which nothing is stopping you from doing. You can also [exclude whole `.Rmd` files from purling using the `.nopurl.Rmd` filename suffix](https://pkgpurl.rpkg.dev/reference/purl_rmd.html#-rmd-files-excluded-from-purling).
65
67
66
68
</details>
67
69
<details>
@@ -108,19 +110,9 @@ Unfortunately, there are also a few notable **drawbacks** of the R Markdown form
108
110
👎 <strong>Additional workflow step</strong>
109
111
</summary>
110
112
111
-
The pkgpurl approach on writing R packages in the R Markdown format introduces *one* additional step at the very beginning of typical package development workflows: Running [`pkgpurl::purl_rmd()`](https://pkgpurl.rpkg.dev/dev/reference/purl_rmd.html) to generate the `R/*.gen.R` files from the original `Rmd/*.Rmd` sources before documenting/checking/testing/building the package. Given sufficient user demand, this could probably be integrated into [devtools](https://devtools.r-lib.org/)’ functions in the future, so that no additional action has to be taken by the user when relying on RStudio’s built-in package building infrastructure.
112
-
113
-
For the time being, it’s recommended to set up a custom shortcut[^3] for one or both of [`pkgpurl::purl_rmd()`](https://pkgpurl.rpkg.dev/dev/reference/purl_rmd.html) and [`pkgpurl::process_pkg()`](https://pkgpurl.rpkg.dev/dev/reference/process_pkg.html) which are registered as [RStudio add-ins](https://rstudio.github.io/rstudioaddins/).
114
-
115
-
</details>
116
-
<details>
117
-
<summary>
118
-
👎 <strong>Differing setup</strong>
119
-
</summary>
120
-
121
-
Setting up a new project to write an R package in the R Markdown differs slightly from the classic approach. A suitable convenience function like `create_rmd_package()` to set up all the necessary parts could probably be added to [usethis](https://usethis.r-lib.org/) in the future.
113
+
The pkgpurl approach on writing R packages in the R Markdown format introduces *one* additional step at the very beginning of typical package development workflows: Running [`pkgpurl::purl_rmd()`](https://pkgpurl.rpkg.dev/reference/purl_rmd.html) to generate the `R/*.gen.R` files from the original `Rmd/*.Rmd` sources before documenting/checking/testing/building the package. Given sufficient user demand, this could probably be integrated into [devtools](https://devtools.r-lib.org/)’ functions in the future, so that no additional action has to be taken by the user when relying on RStudio’s built-in package building infrastructure.
122
114
123
-
For the time being, you can use my ready-to-go [R Markdown Package Development Template](https://gitlab.com/salim_b/r/pkg-dev-tpl) as a starting point for creating new R packages in the R Markdown format.
115
+
For the time being, it’s recommended to set up a custom shortcut[^3] for one or both of [`pkgpurl::purl_rmd()`](https://pkgpurl.rpkg.dev/reference/purl_rmd.html) and [`pkgpurl::process_pkg()`](https://pkgpurl.rpkg.dev/reference/process_pkg.html) which are registered as [RStudio add-ins](https://rstudio.github.io/rstudioaddins/).
124
116
125
117
</details>
126
118
<details>
@@ -173,7 +165,7 @@ Some of pkgpurl’s functionality is controlled via package-specific global conf
0 commit comments