Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Style for examples in roxygen or .Rd files #332

Closed
nfultz opened this issue Jan 26, 2018 · 11 comments

Comments

@nfultz
Copy link

commented Jan 26, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Jan 26, 2018

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 #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

This comment has been minimized.

Copy link
Collaborator

commented Jan 26, 2018

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

This comment has been minimized.

Copy link
Author

commented Jan 26, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Jan 26, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Feb 9, 2018

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

@krlmlr

This comment has been minimized.

Copy link
Member

commented Feb 23, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Mar 23, 2018

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

@krlmlr

This comment has been minimized.

Copy link
Member

commented Mar 23, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Mar 25, 2018

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

@lorenzwalthert lorenzwalthert referenced this issue Mar 25, 2018
5 of 5 tasks complete
@lorenzwalthert

This comment has been minimized.

Copy link
Collaborator

commented Jul 9, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Jul 27, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.