26

I would like to use a directory structure within the R folder for the source code of a package. For example, within my R folder I have an algos folder with functions I want to export and document. However roxygen2 by default does not seem to go through the subfolders of the R folder.

I tried to use the @include keyword as follows for a file at `R/algos/algo1.r'

#' @include algos/algo1.r

but without success. Is there a simple way to use subfolder for the R source code?

tlamadon
  • 970
  • 9
  • 18
  • 1
    Is there a particularly strong reason you want to go against the [required package structure](http://cran.r-project.org/doc/manuals/R-exts.html#Package-structure)? – Dason Feb 15 '13 at 19:59
  • 2
    no reason, it does not seem to say that one could not use subdirectories within the `R` folder, does it? – tlamadon Feb 15 '13 at 20:00

2 Answers2

32

Writing R Extensions has this to say (in Section 1.1.5) about subdirectories under the R directory:

The R and man subdirectories may contain OS-specific subdirectories named unix or windows.

Implied in this is that they can't have other subdirectories other than those two. This is confirmed in an r-devel thread and again later in another r-devel thread.

Brian Diggs
  • 57,757
  • 13
  • 166
  • 188
  • What is the reason for this limitation? – adam May 11 '19 at 12:27
  • @adam I don't think a reason has ever been given. I'm just guessing, but I imagine it was an implicit requirement based on how some aspect of the build tool was (is?) written. – Brian Diggs May 13 '19 at 22:10
  • 6
    that's a really weird limitation, how do i suppose to organize many dozens of functions/files? – simplyPTA Aug 09 '21 at 12:57
  • @simplyPTA Write [‘box’ modules](https://klmr.me/box/) instead of packages. ‘box’ supports hierarchically organised code (amongst several other things that packages don’t support) and is essentially a modern module system that replaces packages. Disclaimer: I made it. – Konrad Rudolph Aug 01 '22 at 21:09
  • Thank you @konrad-rudolph for the suggestion and for your work, I'm already aware of it. Sadly my last year project must be a `{golem}` package so I haven't found a way to use `{box}`. For the current project, I want to use `{targets}` but again `{box}` doesn't work with it :((( Do you know whether `{targets}` could be supported? – simplyPTA Aug 03 '22 at 07:25
  • 1
    @simplyPTA Support for 'targets' is definitely on the road map, although I haven't yet found time to confer with Will about how to best do this. As for 'golem', that package is obviously specifically targeting conventional packages, but you arguably don't need to it to develop Shiny apps anyway (though I've used it successfully in the past myself). – Konrad Rudolph Aug 03 '22 at 09:18
  • @simplyPTA I should clarify that there's (as far as I know) nothing in 'box' which prevents its use with 'targets'. However, 'targets' makes some assumptions about how R code is structured (= as packages), so support for modules would have to be added *to 'targets'*. (The same is generally true for 'golem' but, unlike for 'targets', I think being tied to packages makes a certain amount of sense here. Rather than adding support for modules, there should probably be a separate project for Shiny + 'box'. I know that Appsilon has something along these lines.) – Konrad Rudolph Aug 03 '22 at 09:26
  • Thank you @konrad-rudolph for the info. Sadly I couldn't use it for past and current projects, but definitely give it a try in the future – simplyPTA Aug 03 '22 at 09:52
0

Another straightforward alternative that I've started to use is to simply define related functions within the same .R file and name these files something that unifies the functions. In the example above one could have something like algos.R in the /R folder and within algos.R:

#' @roxygen_header1
#' @export

algo1 <- function(...){}


#' @roxygen_header2
#' @export

algo2 <- function(...){}

I think this makes navigating /R much more intuitive (at least for the developer, but probably for users too)

Nate Hall
  • 64
  • 1
  • 7