Style for examples in roxygen or .Rd files

[nfultz]

It would be cool if we could also restyle the examples in our R package, since that's code that end users might actually see.

[lorenzwalthert]

Thanks @nfultz, sounds like a cool idea but probably that's not straight forward if it should be done in a safe and clean way. We'd probably have to

• parse roxygen comments somehow from all R/ files (maybe this is similar to style R Markdown (code chunks) #13 in some sense) by identifying the @example(s) header / tag and the corresponding content.
• removing the roxygen comment prefixes (#') for these lines.
• styling the content.
• re-adding royxgen comment prefixes and header.
• inserting the styled expression.

Indeed this seems really similar to #13 and I think for consistency, the infrastructure introduced in #233 should be re-uesd / extended as much as possible so that we can avoid code duplication.

Any interest to get us started with a PR? If yes, please make sure to follow the contribution guide lines outlined here. I am happy to review. Otherwise, this will be postponed at least a few months due to time constraints.

[lorenzwalthert]

Anyways I think we should limit our attention to roxygen source code in a first step if that's ok for you since the majority of package developers uses roxygen.

[nfultz]

Another idea - there is all ready existing tools to go from roxygen => Rd (roxygen2 package) and from Rd examples => R (R CMD check does so, for example package-Ex.R). Yihui has written a converter for Rd => roxygen https://yihui.name/rd2roxygen/

So the missing link could be from an examples .R => Rd, which would give a round trip of:

ugly roxygen => ugly Rd => ugly package-Ex.R => styler package-Ex.R => pretty Rd => pretty roxygen

styler would just need to be "compatible" with the tool chain and maintain the example metadata already present in package-Ex.R.

You might imagine a similar flow for R markdown, by going through knitr::spin and knitr::purl to go to/from regular R scripts.

[lorenzwalthert]

Ok. I think it's cleaner if we can style the source code directly instead of a derivative of it. Also, the mapping from pretty .Rd back to the source file line where the example stems from seems to make things complicated IMHO. What do you think? Did you take a look at #233? Instead of separating out code / non code from an Rmd and styling this, we want to separate @example(s) roxygen vs non-examples roxygen so I think there is quite some overlap.

[lorenzwalthert]

Rumours has it that @jonmcalder will take a stab on that issue sometime soon...

[krlmlr]

Borderline related: I sometimes wish there was a tool that adds indention for the second, third, ... lines of @param. Might be out of scope for styler, though.

[lorenzwalthert]

I created stylermd a few months ago to make markdown text 80 characters long, maybe that fits there.

[krlmlr]

But this seems to be for .Rmd files? Or do you plan to extend it to cover R source files with roxygen-like comments?

[lorenzwalthert]

Yes maybe, but it's not a top priority for me now.

[lorenzwalthert]

It seems as we finally managed to implement this. Anyone interested in testing? I tested on styler and ggplot2 source code and I did not get any unexpected problems. You can install the version from the corresponding branch of #381.

remotes::install_github("r-lib/styler#381")

Any feedback welcome. All top-level APIs gain an argument include_roxygen_examples that default to TRUE.

[lorenzwalthert]

We've finally merged #381 into master (after I had to make quite a few more tweaks to it). Thanks @nfultz for the idea.