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)
Related
I want to cite another package (the whole package, not just a function from it) in the documentation of some functions I'm developing. I am using Roxygen2 comments to document my package functions.
I cannot find a way to create a link to a whole third-party package using Roxygen2. To link to a package function, one would write [pkg::fun()] but I don't know how to create a link to the package itself.
Some packages expose a general man page, and it's possible to link to it via e.g. [pkg::pkg].
But many packages don't have this and there's just a general package vignette with the list of functions and a link to the description:
Such page can be reached by clicking on a package name in the packages tab in RStudio.
How can I link to it from a function documentation made in Roxygen2 markdown.?
You cannot link to the page that comes up when you click on the name of a package in RStudio's Packages pane. RStudio invisibly calls help(package = "<name>"), which renders the package's index.
From the R-exts manual:
The markup \link{foo} (usually in the combination \code{\link{foo}}) produces a hyperlink to the help for foo. Here foo is a topic, that is the argument of \alias markup in another Rd file (possibly in another package).
Hence \link and the equivalent Markdown markup supported by roxygen2 can only link to topics. A package index is not a topic in this sense because there is no corresponding Rd file.
It might be best just to remind users that they can use help to access the index of the package to which you are referring.
I made a package in R called "my_package_name". When I run ?my_package_name or ??_my_package_name, no results are found. I want a help file to be loaded in the same way that ?ggplot2 loads a package help file.
I can run ?my_function_name to obtain the help files for my functions. However, this does not work with my package name, even though the description file is complete. I found that help(package = my_package_name) loads a page that contains the description file and help pages, but I would like load a page with ?my_package_name.
I would say that the easiest way is probably to run the following from the usethis package. It will create the file needed to have your package documentation
usethis::use_package_doc()
I suggest reading the documentation of the function to understand what's going on under the hood.
I am currently developing an R package and want it to be as clean as possible, so I try to resolve all WARNINGs and NOTEs displayed by devtools::check().
One of these notes is related to some code I use for generating sample data to go with the package:
checking top-level files ... NOTE
Non-standard file/directory found at top level:
'generate_sample_data.R'
It's an R script currently placed in the package root directory and not meant to be distributed with the package (because it doesn't really seem useful to include)
So here's my question:
Where should I put such a file or how do I tell R to leave it be?
Is .Rbuildignore the right way to go?
Currently devtools::build() puts the R script in the final package, so I shouldn't just ignore the NOTE.
As suggested in http://r-pkgs.had.co.nz/data.html, it makes sense to use ./data-raw/ for scripts/functions that are necessary for creating/updating data but not something you need in the package itself. After adding ./data-raw/ to ./.Rbuildignore, the package generation should ignore anything within that directory. (And, as you commented, there is a helper-function devtools::use_data_raw().)
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.
So, I'd like to reference one of my package vignettes inside the roxygen2 comments of a function but I'm having a hard time understanding how to do it.
More generally, how do we reference documents inside /inst/doc? E.g. I'd like to reference /inst/doc/mypdf.pdf inside the roxygen2 comments for myFunc. What would that look like? Is it even possible?
I just tell people to run the code that opens the vignette:
#' For more details see the help vignette:
#' \code{vignette("help", package = "mypkg")}
I know this is 4 years old...and hadley provided the answer...but I'd like to offer another option:
\href{../doc/help.html}{\code{vignette("help", package = "mypkg")}}
This gives a direct link to opening the vignette, and provides the code to show the user how to open it on their own.