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
Related
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.
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().
While working on my first R package a noticed that when the package structure gets created in the man directory "man" there is a documentation file for each function/method in the code.
In order to stay DRY (don't repeat yourself) I used some functions as "auxiliary" functions in loops or iteration. How can I tell R that I do not want to provide any documentation for them given that they should not be called directly by the end user?!?!
Use the roxygen2 and devtools packages to document your functions and build your package.
#' Function 1 Title
#'
#' Describe what function 1
#' does in a paragraph. This function
#' will be exported for external use because
#' it includes the #export tag.
#'
#' #param parameter1 describe the first parameter
#' #param parameter2 describe the second parameter
#' #examples
#' function1(letters[1:10], 1:10)
#' #export
function1 <- function(parameter1, parameter2) {
paste(parameter1, parameter2)
}
#' Function 2 Title
#'
#' Description here. This will not
#' be added to the NAMESPACE.
#'
#' #param parameter1
function2 <- function(parameter1) {
parameter1
}
Once you have all your documentation, use the tools in the devtools package to build, document, and check your package. It will automatically update the man files and DESCRIPTION, and add / remove functions from the NAMESPACE.
document()
build()
check()
I also recommend using the rbundler package to control how you load packages.
If you do not export them via the NAMESPACE you are not expected to provide documentation.
Another (older) was is too simple create one, say, internal.Rd and define a bunch of \alias{foo}, \alias{bar}, \alias{frob} and that way codetools is happy too.
thanks #Jojoshua-ulrich and #dirk-eddelbuettel
According to "Writing R Extensions":
The man subdirectory should contain (only) documentation files for the objects in the package in R documentation (Rd) format. The documentation filenames must start with an ASCII (lower or upper case) letter or digit and have the extension .Rd (the default) or .rd. Further, the names must be valid in ‘file://’ URLs, which means9 they must be entirely ASCII and not contain ‘%’. See Writing R documentation files, for more information. Note that all user-level objects in a package should be documented; if a package pkg contains user-level objects which are for “internal” use only, it should provide a file pkg-internal.Rd which documents all such objects, and clearly states that these are not meant to be called by the user. See e.g. the sources for package grid in the R distribution for an example. Note that packages which use internal objects extensively should not export those objects from their namespace, when they do not need to be documented (see Package namespaces).
By the way, is there any convention to include comments in the code so that man grabs the function description, arguments description etc directly from the code?
Actual question
How do I avoid Rd file name conflicts when
a S4 generic and its method(s) are not necessarily all defined in the same package (package containing (some of) the custom method(s) depends on the package containing the generic) and
using roxygenize() from package roxygen2 to generate the actual Rd files?
I'm not sure if this is a roxygen2 problem or a common problem when the generic and its method(s) are scattered across packages (which IMHO in general definitely is a realistic use-case scenario if you follow a modular programming style).
What's the recommended way to handle these situations?
Illustration
In package pkga
Suppose in package pkga you defined a generic method foo and that you've provided the respective roxygen code that roxygenize() picks up to generate the Rd file:
#' Test function
#'
#' Test function.
#'
#' #param ... Further arguments.
#' #author Janko Thyson \email{janko.thyson##rappster.de}
#' #example inst/examples/foo.R
#' #docType methods
#' #rdname foo-methods
#' #export
setGeneric(
name="foo",
signature=c("x"),
def=function(
x,
...
) {
standardGeneric("xFoo")
}
)
When roxygenizing() your package, a file called foo-methods.Rd is created in the man subdirectory that serves as the reference Rd file for all methods that might be created for this generic method. So far so good. If all of the methods for this generic are also part of your package, everything's good. For example, this roxygen code would make sure that documentation is added to foo-methods.Rd for the ANY-method of foo:
#' #param x \code{ANY}.
#' #return \code{TRUE}.
#' #rdname foo-methods
#' #aliases foo,ANY-method
#' #export
setMethod(
f="foo",
signature=signature(x="ANY"),
definition=cmpfun(function(
x,
...
) {
return(TRUE)
}, options=list(suppressAll=TRUE))
)
However, if package pkga provides the generic for foo and you decide in some other package (say pkgb) to add a foo-method for x being of class character, then R CMD check will tell you that there is a name clash with respect to Rd file names and/or aliases (as there already exists a Rd file foo-methods.Rd in pkga):
In package pkgb
#' #param x \code{character}.
#' #return \code{character}.
#' #rdname foo-methods
#' #aliases foo,character-method
#' #export
setMethod(
f="foo",
signature=signature(x="character"),
definition=cmpfun(function(
x,
...
) {
return(x)
}, options=list(suppressAll=TRUE))
)
To be more precise, this is the error that's thrown/written to file 00install.out
Error : Q:/pkgb/man/foo-methods.Rd: Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'pkgb'
Due dilligence
I tried to change the values for #rdname and #aliases to foo_pkgb* (instead of foo*), but \title and \name still are set to foo when roxygenizing and thus the error remains. Any ideas besides manually editing the Rd files generated by roxygenize()?
EDIT 2012-12-01
In light of starting the bounty, the actual question might get a slightly broader flavor:
How can we implement some sort of an "inter-package" check with respect to Rd files and/or how can we consolidate S4 method help files scattered across packages into one single Rd file in order to present a single source of reference to the end-user?
The basic question is indeed "roxygenize"-only.
That's why I never had seen the problem.
While there are good reasons for the roxygenizing approach of package development,
I still see a very good reason not to go there:
Plea for much less extreme roxygenation
The resulting help pages tend to look extremely boring, not only the auto generated *.Rd files but also the rendered result.
E.g.
examples are often minimal, do not contain comments, are often not well formatted (using space, / new lines /..)
Mathematical issues are rarely explained via \eqn{} or \deqn{}
\describe{ .. } and similar higher level formatting is rarely used
Why is that? Because
1) reading and editing roxygen comments is so much more
"cumbersome" or at least visually unrewarding
than reading and editing *.Rd files in ESS or Rstudio or (other IDE that has *.Rd support built in)
2) If you are used that documentation
is the thing that's automatically generated at the end of your package building/checking
you typically tend to not considerung well written R documentation as something important
(but rather your R code, to which all the docs is just a comment :-)
The result of all that: People prefer writing documentation about their functions in vignettes or even blogs, github gists, youtube videos, or ... where it is very nice at the time of authoring, but is
pretty much detached from the code and bound to get outdated and withering (and hence, via Google search misleading your useRs)
--> The original motivation of roxygen of having code and documentation in the same place is entirely defeated.
I like roxygen and use it extensively at the time I create a new function...
and I keep and maintain it as long as my function is not in a package, or is not exported.
Once I decide to export it,
I run (the ESS equivalent of) roxygenize() once
and from then on take the small extra burden of maintaining a *.Rd file that is well formatted, contains its own comments (for me as author), has many nice examples, has its own revision control (git / svn / ...) history, etc.
I managed to generate NAMESPACE and *.Rd files for S4 methods for generics defined in another package than mine.
It took me the following steps:
Create NAMESPACE by hand as a workaround to a known roxygen2 bug.
Writing a NAMESPACE by hand is not so difficult at all!
Switch off NAMESPACE generation by roxygen2 in RStudio:
Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE.
import the package containing the generic and export the S4 methods using exportMethods.
Write separate roxygen2 documentation for each of the S4 methods. Do not combine roxygen2 documentation (as I generally do for different methods of the same generic).
Add explicit roxygen tags #title and #description to the roxygen documentation of the S4 methods. Write #description explicitly, even if its value is identical as #title.
That makes it work for me.
I have a question about creating an .Rd file for my R package using the roxygen2 package.
It is clear to me that, for documenting R functions, I can use C-c C-o in emacs to generate comments above the function, and then fill them out, followed by roxygenize("pkg"). In this way, I have .Rd files for the R functions. However, I am not sure how can I get .Rd file for the data examples and the package itself? Currently, I am using prompt("data") to generate data.Rd and promptPackage("pkg") to generate pkg-package.Rd. I have to put these files into the man folder, and then edit them separately. How can I document data and package in a similar way like documenting R functions using roxygen2?
Thank you very much!
For data, see this previous question on SO which suggests:
#' This is data to be included in my package
#'
#' #name data-name
#' #docType data
#' #author My Name \email{blahblah##roxygen.org}
#' #references \url{data_blah.com}
#' #keywords data
NULL
I would suspect that you can do the same for pkg-package.Rd. If it must be in roxygen format, consider
a manual translation or
the rd2roxygen package.