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
Closed

Style for examples in roxygen or .Rd files #332

nfultz opened this issue Jan 26, 2018 · 11 comments

Comments

@nfultz
Copy link

@nfultz nfultz 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
Copy link
Collaborator

@lorenzwalthert lorenzwalthert 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.

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert 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.

Loading

@nfultz
Copy link
Author

@nfultz nfultz 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.

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert 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.

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert commented Feb 9, 2018

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

Loading

@krlmlr
Copy link
Member

@krlmlr krlmlr 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.

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert commented Mar 23, 2018

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

Loading

@krlmlr
Copy link
Member

@krlmlr krlmlr 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?

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert commented Mar 25, 2018

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

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert 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.

Loading

@lorenzwalthert
Copy link
Collaborator

@lorenzwalthert lorenzwalthert 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.

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants