I am trying to make a package but when I run document() it prints NAMESPACE not generated by roxygen2. Skipped. I am trying to use ggplot2,XML, R6 packages in my functions. I am importing them in the following way:
#' #rdname visualization
#' #param hist_data A table of weather variables with PWS created by hist_data function
#' #param variable A character string of variable name
#' #examples
#' table <- getWeather(city = "San Francisco", state="CA")
#' please <- getConditionsTable(table, "2015-03-09")
#' tab <- hist_data(table, please)
#' head(tab)
#' plot_variable_across_all_pws(hist_data=tab, variable="tempi")
#' #import ggplot2
#' #import XML
#' #import R6
I am wondering what might be causing this error and there is nothing in my Namespace except for exportPattern("^[^\\.]")
Also, I was going over R packages book by Hadley http://r-pkgs.had.co.nz/namespace.html
And confused by the line :
"Note that you can choose to use roxygen2 to generate just NAMESPACE, just man/*.Rd, or both. If you don’t use any namespace related tags, roxygen2 won’t touch NAMESPACE. If you don’t use any documentation related tags, roxygen2 won’t touch man/."
Is this what I'm doing wrong? or missing?
Backup NAMESPACE file, if you need it for future use
Delete the NAMESPACE file
Run devtools::document(), so that roxygen2 will generate new NAMESPACE file in the package source directory
*** make sure you have #export tag in the roxygen2 doc section of the R source file.
I think that devtools tries to avoid overwriting DESCRIPTION and NAMESPACE files that it didn't generate itself (to avoid angst if you have meticulously typed them in yourself, instead of using embedded roxygen comments in your r code). It isn't always possible but it tries.
The main mechanism, as I understand it, is to post a comment at the top of the file when it generates the file, and then later on, look for that comment (there are tricky bits round the edge, for example if you use #includes to create the Collate order in the DESCRIPTION file, but I don't think that is your problem here.)
An example of such a comment is
# Generated by roxygen2 (4.1.0.9001): do not edit by hand
The not generated by ... message is alerting you to this, and letting you know devtools is not going to use roxygen2 to make a NAMESPACE file for you. You possibly have the one you mention without the comment because you used RStudio to start your package, rather than devtools::create() ?
If you just delete the NAMESPACE file, I think devtools::document() would then work for you.
BTW You have a typo in the example code above (you have#' #import ggplo2 instead of #' #import ggplot2)
Thanks to #jsta's solution and I copied the following line # Generated by roxygen2: do not edit by hand at the top of the NAMESPACE file, and then with an empty line.
Then I ran devtools::document() in the console and it automatically replaced the existing NAMESPACE file.
I think that top line is just what roxygen will look for to see if that file is generated by roxygen.
None of the preceding examples worked for me. If I deleted the NAMESPACE file then roxygen complained there was no NAMESPACE. If I deleted and re-created a NAMESPACE file (with `touch, e.g. RStudio: Building package with roxygen2. Not producing NAMESPACE file) then roxygen complained that the file was not created with roxygen.
The solution was to copy a NAMESPACE file from another project that was created with roxygen.
Also one may simply delete everything from NAMESPACE and add leave one line: exportPattern("^[[:alpha:]]+")
If the file NAMESPACE is changed manually, devtools::document() fails to overwrite this file, that is why it leaves as before. When you delete the text from the NAMESPACE file and insert this line, devtools::document() thinks that the file is new and overwrites it.
Related
I am working on a R package that uses an external 3rd party dll to load data. I have written wrapper functions to that external dll that I can call with .C()
Assume that my package is called mypackage and the external is called xternal.dll. It seems that to load the mypackage.dll that is generated during compilation it is necessary that external.dll is loaded first. I am using roxygen2 to manage the NAMESPACE file, and I have used the #' #useDynLib tags. Unfortunately when roxygen2 writes the NAMESPACE file it adds the useDynLib calls in the lexical order of the shared object being called like A-Z, a-z.
Is there a way to control the order of the useDynLib in the namespace by roxygen2?
So far I have found the follwing solutions and neither of them seems to be particularly compelling:
Renaming my package to be lexically ordered after the external dll.
Managing the NAMESPACE file manually.
Example:
The function foo.R:
#' #export
#' #useDynLib xternal
#' #useDynLib mypackage
foo <- function(){
return(FALSE)
}
results in the NAMESPACE after calling devtools::document():
# Generated by roxygen2: do not edit by hand
export(foo)
useDynLib(mypackage)
useDynLib(xternal)
The package would fail to load, however if I manually swap the two useDynLib lines the package installs and works fine.
After a very helpful hint received on GitHub:
The solution is to use the #rawNamespace tag, that writes a verbatim line into the NAMESPACE file:
foo.R:
#' #export
#' #rawNamespace useDynLib(xternal); useDynLib(mypackage)
foo <- function(){
return(FALSE)
}
results in a NAMESPACE file:
# Generated by roxygen2: do not edit by hand
export(foo)
useDynLib(xternal); useDynLib(mypackage)
and the shared objects are loaded in the correct order.
I imagine this is a simple thing that I keep overlooking in the documentation, but I can't seem to figure out how to get package-level documentation to work in R. I'm not referring to function or class-specific documentation, but the documentation that you get when you type, for example, ?stats.
I've followed the general instructions I've found on the web, creating a sckeleton documentation file saved as .R. The .R file is copied with the package scripts, but the help documentation doesn't get made into a .Rd file (unless I add a function definition also named after the package).
An example of what I've tried:
#'_PACKAGE
#'MyPackage
#'
#'MyPackage description
#'
#'MyPackage details
#'#alias{MyPackage}
#'#alias{MyPackage-package}
I'm having a hard time finding good examples of how to set up general package documentation, for some reason. I've written quite a few function help files, and I know my package help file is being found by roxygen, but it's unclear why I can't generate an .Rd from it.
Answer courtesy of #slickrickulicious in the comments above:
I needed to add NULL at the end of my documentation file and include '#name MyPackage'. Doing so generated the package help file correctly.
I made my package (called pkgName) using devtools and already had a file named pkgName_package.R that was automatically generated. It contained the following lines:
#' #keywords internal
#' #aliases pkgName-package
"_PACKAGE"
After removing the first line, #keywords internal, and rebuilding, pkgName-package was a documented topic that appeared at the top of the reference manual.
I am making an R package in Rstudio and I selected the option Configure Build Tools > Configure and select Use roxygen to generate NAMESPACE. I wrote my functions in Rcpp and this is what the NAMESPACE looks like when I generate it with roxygen2:
# Generated by roxygen2 (4.1.1): do not edit by hand
export(function1)
export(function2)
export(function3)
export(function4)
Since my functions are written with Rcpp, which I then export, then they will used in R via .Call. However, from writing R extensions we should use useDynLib() in such a case. This is why I think I am getting an error when I try to call function1 and the error is:
Error in .Call("Mypackage_function1", PACKAGE = "Mypackage", var1, :
"Mypackage_function1" not available for .Call() for package "Mypackage"
When I use the default NAMESPACE when I start a project in Rstudio, I have the following in NAMESPACE:
useDynLib(packagename)
exportPattern("^[[:alpha:]]+")
importFrom(Rcpp, evalCpp)
When I use the default NAMESPACE I can call the functions using .Call however I get a warning when I check the package that I am not generating the NAMESPACE using roxygen.
Is there a fix for this? Any advice is appreciated.
This is unrelated to the usage of RStudio: For Roxygen to generate the relevant useDynLib specification, you need to use the #useDynLib tag in a Roxygen doc comment:
#' #useDynLib packagename
You can do this anywhere (where you can use normal Roxygen comments) but it makes sense to put this into the package documentation, rather than the documentation of a specific function. Usually this resides in a file called R/packagename-package.r:
#' My package documentation
#' … bla bla …
#' #name packagename
#' #docType package
#' #useDynLib packagename
NULL
As in this question, I would like to include citations to articles in function documentation. I use roxygen2 for all documentation, and it appears that there was a pull request to roxygen2 with the necessary functionality, but Hadley turned it down since roxygen2 was in maintenance mode. Have things changed since then? Is there another way to cite/ include article references stored in BibTeX format?
The Rdpack package promises to deliver the functionality that you requested.
To get set up, you also need to add the line RdMacros: Rdpack to your package's DESCRIPTION file (note the capital M), and add Rdpack to the Imports: field.
Then you can save your bibtex library in to inst/REFERENCES.bib, and cite them in your documentation with:
#' #references{
#' \insertRef{bibtexKey}{YourPackageName}
#' }
#'
#' # The below line ought to be included in at least one of your documentation
#' # sections, so that roxygen2 adds Rdpack to your NAMESPACE file.
#'
#' #importFrom Rdpack reprompt
I initially encountered some errors when first using the package; re-starting R seemed to do the trick.
Warnings about unknown macro '\insertRef' will be encountered if building documentation with devtools::document(), as devtools does not read the 'RdMacros' line of the DESCRIPTION file; they can be safely ignored. The references may not be rendered correctly by devtools, but will be when the package is finally built; to view them in their proper formatting in the interim you can run R CMD Rd2pdf from a separate command window.
Nicely summarized by ms609. I would add that the releases of Rdpack in 2018 provided also macros for citation and the ability to produce the bibliography with a single command insertAllCited{}. Vignette Inserting_bibtex_references, linked also by ms609, provides up-to-date information.
Rdpack::viewRd() can be used to view the rendered citations without building the package, something like:
Rdpack::viewRd("./man/filename.Rd") # text
Rdpack::viewRd("./man/filename.Rd", type = "html") # html
This may be particularly useful for roxygen2 users since roxygen2 processes the Rd files but doesn't render the references. Just don't forget to update the documentation using devtools::document() or another suitable command before invoking Rdpack::viewRd().
I've thrown together a bunch of my utility functions into a package. However, I can't seem to access them after I've installed the package. I get errors of the form Error: object 'function_name' not found
Building the package, there are no error messages
Installing the package from source, there are no error messages
Loading the package, there are no error messages (library() nor require())
The package documentation is accessible once loaded
I'm using roxygen2 to generate documentation and the namespace
Any thoughts?
Do you use a NAMESPACE and forgot to add the object in question?
If you're using roxygen2, have you remembered to add #' #export function_name to the functions you want included in the namespace?
If the function name is not exported, you may need to use ":::"
pkgname:::function_name
I believe that CRAN now requires a NAMESPACE, and I think R 2.14.x may even require them.
The same problem for me, you need to change NAMESPACE file. sometime NAMESPACE's content looks like this:
# Generated by roxygen2: do not edit by hand
But you need to change it by hand, like this:
# Generated by roxygen2: do not edit by hand
export("function_name1", "function_name2")
OR use exportPattern("^[^\\.]") to export all function.