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.
Related
Cross posted from: https://community.rstudio.com/t/link-to-r6-method-from-separate-package-in-help-pages-and-pkgdown/134702
I'm currently writing an R package and would like to link to the help page for an R6 method in a separate package. The page I want to link to is here: https://mc-stan.org/cmdstanr/reference/model-method-sample.html, and there is an .Rd file for the method as well (https://github.com/stan-dev/cmdstanr/blob/master/man/model-method-sample.Rd). Finally, I can also access the help page from R directly with ?cmdstanr::`model-method-sample`.
However, when I try to add a link to my own help page using the normal link to another package syntax described here, [cmdstanr::`model-method-sample`], I get this error:
Warning: Link to unknown topic: cmdstanr::`model-method-sample`
I feel like there must be some way to link to this help page, given that it definitely exists and has an .Rd page, but I haven't found a solution yet. Has anyone else run into this problem or know the solution?
I think you (or Roxygen) are using the wrong syntax for the link. According to Writing R Extensions, the Rd syntax should be:
\link[cmdstanr]{model-method-sample}
I'm not sure how to generate this from Roxygen, but it appears to work as-is if I put it in Roxygen comments.
If you want the link with different text, the syntax is
\link[cmdstanr:model-method-sample]{link text}
Long story short:
My aim is to submit a R package developed with roxygen2 to CRAN, and I need to find some guidelines on writing and documenting hidden functions.
More details:
I am writing my first R package using roxygen2 in Rstudio. I have documented all the functions I wrote so far, so that my collaborators can easily understand their purpose before going into the details of the script. All the functions that are of no use to the user, but necessary to the package, are not exported in the namespace and eliminated from the package manual/index (#keywords internal). At the same time, my collaborators can still read their documentation using the help of Rstudio.
Eventually, I would like to remove the documentation of these "hidden functions" from the help because there is no reason to keep it. I was considering to follow a suggestion I found in other posts, that is changing #' with ## in the documentation created with roxygen2. However, I am not sure this is the correct procedure to implement, and if removing the documentation of a function in the help and the manual is compatible with CRAN requirements.
Can anyone point me to some guidelines related to this issue, or has any experience to share?
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.
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)