[Doc] How to setup extended roxygen2 funcionality?

[ramiromagno]

Hi @hadley and @gaborcsardi:

I've read the Extending roxygen2 vignette.

And I now it reads:

This vignette is very rough, so you are expected to have also read some roxygen2 source code to understand all the extension points.

But you also mention:

Hopefully, it’s useful enough to help you get started, and if you have problems, please file an issue!

So here it goes. :)

My question is not related to the actual writing of the S3 methods necessary to create new tags or roclets. I think the vignette is fine and indeed reading the source code of roxygen2 complements it nicely.

My question/request is whether you could also explain briefly what is the minimal setup that goes into an R package that extends roxygen2, and how to use from another package.

So assume I have package A installed, that includes code to extend roxygen2 (as explained in the vignette), providing some new tags and roclets. Assume also I have package B where I'd like to use those extensions.

If I am using RStudio, and using devtools::document() (Ctrl+Shift+D) to generate documentation for package B, what kind of minimal setup do I need? Is there some metadata I need to add to DESCRIPTION of any of the packages?

Also, are there any other good practices that you recommend? Besides using package A name as common prefix for tags/roclets.

Many thanks!

[bryanhanson]

@ramiromagno I was in the same situation a while back, and wrote a small package to extend roxygen2. Take a look: such a package can be quite small but does need all the infrastructure to pass CRAN.

https://github.com/bryanhanson/roxut

[ramiromagno]

@bryanhanson thank you so much for indicating {roxut}.

I took a look at {roxut} reverse suggests and found that you're using it in the packages ChemoSpecUtils and LearnPCA.

I see that you have in their DESCRIPTION files:

• https://github.com/bryanhanson/ChemoSpecUtils/blob/708258f5d4515b9299d9da573d794ab0ef961d4a/DESCRIPTION#L44

  Roxygen: list(roclets = c("namespace", "rd", "roxut::tests_roclet"))

• https://github.com/bryanhanson/LearnPCA/blob/7e5b9f1b80f728426c98879223e28fe0e5f2ecb9/DESCRIPTION#L40

  Roxygen: list(packages = "roxut", roclets = c("namespace", "rd", "roxut::tests_roclet"), markdown = TRUE)

Was that all the setup you needed to do in the packages using {roxut}?

[ramiromagno]

Trying to document the {ChemoSpecUtils} package with Shift+Ctrl+D (devtools::document()) did not work because it runs document() only with roclets = c('rd', 'collate', 'namespace').

==> devtools::document(roclets = c('rd', 'collate', 'namespace'))

ℹ Updating ChemoSpecUtils documentation
Setting `RoxygenNote` to "7.2.1"
ℹ Loading ChemoSpecUtils
Warning: [checkForPackageWithVersion.R:17] @tests is not a known tag
Warning: [chkGraphicsOpt.R:19] @tests is not a known tag
Warning: [chkSpectra.Spectra2D.R:8] @tests is not a known tag
Warning: [rowDist.R:31] @tests is not a known tag

Trying with:

devtools::document(roclets = c('rd', 'collate', 'namespace', 'roxut::tests_roclet'))

worked as intended:

ℹ Updating ChemoSpecUtils documentation
ℹ Loading ChemoSpecUtils
Writing inst/tinytest/test-checkForPackageWithVersion.R
Writing inst/tinytest/test-chkGraphicsOpt.R
Writing inst/tinytest/test-chkSpectra.Spectra2D.R
Writing inst/tinytest/test-rowDist.R

Isn't there a way of configuring the RProj such that it always includes the roxut::tests_roclet' when calling devtools::document()? Better even, a way to inform devtools::document() to use all the roclets available from a specific package, e.g. {roxut}.

[bryanhanson]

Don't faint, but I don't use RStudio so I can't really help with these short cuts and configurations. I run things with a make file. I would/hope think there must be someway to get RStudio to use the DESCRIPTION file info. See if there is a more direct way to build, check and install w/o the shortcuts.

[gaborcsardi]

You can try editing the .Rproj file directly. I have this:

PackageRoxygenize: rd,collate,namespace

so changing that to

PackageRoxygenize: rd,collate,namespace,roxut::tests_roclet

might work. If it does not, then please open an issue in the rstudio/rstudio repo. Thanks!

[hadley]

I think there’s already an open issue about this problem in rstudio

[ramiromagno]

Hi @gaborcsardi,

Thanks for the tip.

Indeed, adding roxut::tests_roclet to PackageRoxygenize;

PackageRoxygenize: rd,collate,namespace,roxut::tests_roclet

in the .Rproj file does work; it runs devtools::document(roclets = c('rd', 'collate', 'namespace', 'roxut::tests_roclet')) after the shortcut Ctrl+Shift+D.

Do I have to enumerate every single roclet that I might need? Can't I just specify all of them from a specific package?

[gaborcsardi]

Do I have to enumerate every single roclet that I might need? Can't I just specify all of them from a specific package?

I believe so. Unless you write a meta-roclet for this. :)

[ramiromagno]

Thank you @gaborcsardi !