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.
Related
I have created my own package with description file and help paper for every function.
Now if I code ?mypackage::myfunction R displays help paper to myfunction. But when I code ?mypackage R displays "No documentation for ‘mypackage’ in specified packages and libraries:" :(
In case you are not using roxygen2 (but you probably should), you need to create a .Rd file with the general mandatory fields, including a \docType{package}. See section 2.1.4 of the Writing R Extensions.
Apart from the mandatory \name and \title and the pkgname-package
alias, the only requirement for the package overview page is that it
include a \docType{package} statement. All other content is optional.
We suggest that it should be a short overview, to give a reader
unfamiliar with the package enough information to get started. More
extensive documentation is better placed into a package vignette (see
Writing package vignettes) and referenced from this page, or into
individual man pages for the functions, datasets, or classes.
Assuming you are using Roxygen2 to generate your documentation, somewhere you will need something like this saved in a .R file.
#' Title
#'
#' Description
#'
#' #docType package
#' #name varbinq
NULL
This will create a help file for your package that can be accessed when you type ?varbinq
For more information see this section of Hadley Wickham's book entitled R Packages.
If you are using the roxygen2 package for documenting your package called "mypackage", the documented way to do this is to write this code in a file named "mypackage.R":
#' Generate R documentation from inline comments.
#'
#' Roxygen2 allows you to write documentation in comment blocks co-located
#' with code.
#'
#' The only function you're likely to need from \pkg{roxygen2} is
#' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
#' how to format the documentation.
"_PACKAGE"
You will then be able to retrieve your package's help page using:
??mypackage
It is my first experience in writing an R-package. I used roxygen2 by following the instructions given in this link http://kbroman.org/pkg_primer/
Everythig is working fine except few things.. there could be a simpler solution to solve the issues, but I am not finding clues what I am doing wrong. I hope someone here in this blog can give a solution to solve my issues.
First issue is about {\code\link{function-name}} in roxygen2:
In .R script I inlcuded this line:
#' #seealso \code{\link{s2a}}
After documenting (generating .Rd files) there is no hyperlink to s2a ,
in documentation s2a shows like a normal text not like hyperlink..
export(s2a) is listed out in NAMESPACE.
Is there any other place i need to modify ?
Second issue is about data():
I saved the dataset in .Rdata format and placed in the data/ in package directory. I also created the .R script in R/ as like following steps here http://kbroman.org/pkg_primer/pages/data.html
In DESCRIPTION file LazyData: true .
but when I type data(shh) in R console gives a warning message
data(shh)
Warning message:
In data(shh) : data set ‘shh’ not found
Any ideas is of great help:)
It's been a while since you asked this, but I was having the exact same problem with hyperlinks in documentation not appearing correctly, so for anyone who might be having a similar problem: Are you possibly viewing the development documentation? The links don't seem to work there. (You'll know this is the case if you see Using development documentation for your_function_name in your console output when you run ?your_function_name.)
The links should appear in the non-development documentation. To generate this you can try building and reloading your package, for instance by following the steps here: http://r-pkgs.had.co.nz/man.html#man-workflow-2
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 am writing an R package names slidify. The main function in the package is also named slidify. When I run devtools::check, I get a warning that there is a conflict in the Rd files.
I don't want to rename the function, since it succintly conveys what the package is intended for. What is best practice in this situation? Should typing ? slidify lead to the function documentation or package documentation?
Any thoughts would be appreciated.
I'd make a "slidify-package.Rd" file, (or a "slidify-package.R" file with nothing but roxygen comment blocks)
?slidify should lead to the function documentation and slidify?package should lead to the package documentation, and both help pages should have a link to the other (in the seealso section, for example)
I've just started playing around with the roxygen package and I've very happy with the results so far. However I was wondering, is there a way to specify to roxygen that it should ignore certain functions that are not user-accessible?
Specifically, I'd rather not have a .Rd file pop up because I'm using the .onLoad() hook in my package. This function is already documented in the base package so there's no reason for me to re-document it.
Well, I finally found and browsed the Roxygen-devel list at R-forge to see when this would be implemented, and it appears to already be in the version of Roxygen that is on CRAN. The key is to specify use.Rd2=TRUE when calling roxygenize(). Under this mode, Roxygen will skip creating documentation for any functions that are not preceded by Roxygen comments.
This is on their to do list - in the next version, only functions with roxygen documentation will create man files.
Use the internal keyword field (i.e. #keywords internal) to remove the function from the documentation and make it available for experienced users only.
Source: roxygen2 vignette.