Using source subdirectories within R packages with roxygen2

Question

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?

Dykstra

Is there a particularly strong reason you want to go against the required package structure? – Pyriform

no reason, it does not seem to say that one could not use subdirectories within the R folder, does it? – Dykstra

Answer 1

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.

Cartilaginous

What is the reason for this limitation? – Turgite

@Turgite 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. – Cartilaginous

that's a really weird limitation, how do i suppose to organize many dozens of functions/files? – Bekki

@Bekki Write ‘box’ modules 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. – Inbreathe

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? – Bekki

@Bekki 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). – Inbreathe

@Bekki 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.) – Inbreathe

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 – Bekki

Answer 2

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)

Noshow

There is no @roxygen tag, you should use @section instead – Ferriage