Roxygen2: Roxygen not working without a DESCRIPTION file

[stefanoborini]

I have a shiny application that does not require a DESCRIPTION file. Roxygen is unable to scout the code and extract the relevant information from the routines, and produce an API description. There's no reason to make it mandatory to have a DESCRIPTION file if something is not a package.

[gaborcsardi]

Can you please show an example?

[stefanoborini]

There's no example to show. If you run roxygenise() on a directory it complains that there's no DESCRIPTION file.

[gaborcsardi]

Here is an example:

root <- tempfile()
dir.create(root)
setwd(root)
roxygen2::roxygenize()
#> Error: `package.dir` must include a DESCRIPTION file:
#>   * "/private/var/folders/59/0gkmw1yj2w7bf2dfc3jznv5w0000gn/T/Rtmp1zBdAZ/filebc33bc6f4dc" does not.
#> Did you call `roxygenize()` in a directory that is not the package root?

cat("Package: foo\n", file = "DESCRIPTION")
roxygen2::roxygenize()
#> First time using roxygen2. Upgrading automatically...
#> Updating roxygen version in /private/var/folders/59/0gkmw1yj2w7bf2dfc3jznv5w0000gn/T/Rtmp1zBdAZ/filebc33bc6f4dc/DESCRIPTION
#> Warning: roxygen2 requires Encoding: UTF-8
#> Writing NAMESPACE
#> Loading foo
#> Error in idesc_get_version(self, private): No 'Version' field found

cat("Version: 1.0.0\n", file = "DESCRIPTION", append = TRUE)
roxygen2::roxygenize()
#> Warning: roxygen2 requires Encoding: UTF-8
#> Loading foo

^{Created on 2020-07-02 by the reprex package (v0.3.0)}

[stefanoborini]

@gaborcsardi How has this anything to do with it? It's completely pointless. You could have simply created a directory, entered it, and run roxygenise inside it.

[stefanoborini]

$ mkdir xxx
$ cd xxx/
$ R
> roxygen2::roxygenise()
Error: `package.dir` must include a DESCRIPTION file:
  * "/Users/ktwg434/xxx" does not.
Did you call `roxygenize()` in a directory that is not the package root?
> 

Feature requests don't need a reproducible example. Bugs do. This is not a bug. This is a feature request.

[gaborcsardi]

The point of my example is that it shows

• what exactly roxygen2 does if there is no DESCRIPTION file,
• how to easily fix the error by creating a dummy file with a Package and a Version entry,
• it is reproducible and works on all OSes and environments, e.g. RStudio server or Cloud,
• it can be ran with a single copy-paste into an R console.

As for this feature, it seems that a very easy workaround is to actually create a DESCRIPTION file, with those two entries, as the example shows. I have another example below that shows the generated Rd file as well.

Creating a DESCRIPTION file also has the benefit of being able to configure roxygen2 via a Roxygen entry, e.g. turning on markdown support, which most people would want nowadays.

Btw. in addition to creating a DESCRIPTION file, you would also need to move your R source files into an R directory, which is not the standard setup of a Shiny app as I understand. Maybe you use this setup, I don't know. Showing an example would have been useful for this as well.

root <- tempfile()
dir.create(root)
setwd(root)
cat("Package: foo\n", file = "DESCRIPTION")
cat("Version: 1.0.0\n", file = "DESCRIPTION", append = TRUE)

dir.create("R")
cat(file = "R/foo.R", " 
  #' @export
  #' @title Foo foo
  #' @description foobar
  foo <- function() NULL
  "
)

roxygen2::roxygenize()
#> First time using roxygen2. Upgrading automatically...
#> Updating roxygen version in /private/var/folders/59/0gkmw1yj2w7bf2dfc3jznv5w0000gn/T/RtmpT61lwn/filecb14495c48f8/DESCRIPTION
#> Warning: roxygen2 requires Encoding: UTF-8
#> Loading foo
#> Writing NAMESPACE
#> Writing NAMESPACE
#> Writing foo.Rd

cat(readLines("man/foo.Rd"), sep = "\n")
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in R/foo.R
#> \name{foo}
#> \alias{foo}
#> \title{Foo foo}
#> \usage{
#> foo()
#> }
#> \description{
#> foobar
#> }

^{Created on 2020-07-04 by the reprex package (v0.3.0)}

[stefanoborini]

Btw. in addition to creating a DESCRIPTION file, you would also need to move your R source files into an R directory, which is not the standard setup of a Shiny app as I understand. Maybe you use this setup, I don't know.

The point is that roxygen should not need to have a DESCRIPTION file to execute. All it needs to do is to scout whatever directory i tell it to scout, collect the documentation it finds, and write it somewhere.

[hadley]

@stefanoborini given how easy it is to add a DESCRIPTION file, we are not planning to eliminate this constraint in the future. In addition, please consider the tone of your communication in this thread. It came across to me as rather hostile.

[stefanoborini]

@hadley it is hostile because it seems to me that people in the R community design things like Perl.