CreatePackageVignette function #200

jayqi · 2019-03-11T01:52:49Z

Note: This PR is branched off of #181

New function CreatePackageVignette creates an html_vignette version of the package report (long form, no tabs). This makes it easy for any package author to include a pkgnet report as a standard knitr-buildable vignette for their package. It will even render natively inside pkgdown websites.

pkgdown Demo: https://jayqi.github.io/pkgnet/docs/articles/pkgnet_report.html

codecov-io · 2019-03-11T02:04:06Z

Codecov Report

Merging #200 into master will increase coverage by 0.67%.
The diff coverage is 100%.

@@            Coverage Diff            @@
##           master    #200      +/-   ##
=========================================
+ Coverage   91.52%   92.2%   +0.67%     
=========================================
  Files          11      12       +1     
  Lines         920    1000      +80     
=========================================
+ Hits          842     922      +80     
  Misses         78      78

Impacted Files	Coverage Δ
R/AbstractGraphReporter.R	`86.36% <100%> (+0.07%)`	⬆️
R/AbstractPackageReporter.R	`100% <100%> (ø)`	⬆️
R/CreatePackageVignette.R	`100% <100%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 71d7fa8...a1e96ac. Read the comment docs.

bburns632

This is a very slick function! I have a few suggestions to reduce user error I'd like us to discuss.

R/CreatePackageVignette.R

jameslamb

This is great Jay! I love that we're at the point where we can work on these "make pkgnet more fun for people" stage in development. This type of contribution is incredibly important.

I basically approve, but I would like to review one more time once you rebase to master

NEWS.md

R/CreatePackageVignette.R

inst/package_report/package_vignette_template.Rmd

R/AbstractGraphReporter.R

jayqi · 2019-03-15T03:56:38Z

@bburns632 @jameslamb So I ran into a problem with my implementation, and I'd like your input on how to resolve.

Basically, because this is generating an .Rmd file, it's essentially lazily evaluated at package build time.

This means that if you want to provide pkg_path (for test coverage in FunctionReporter), it has to be the path that will work at build time. You can't do an absolute path because Travis will likely have a different absolute path, and it would break your Travis build. (Travis builds will try to build your package and therefore build your vignettes.) So, since in general R CMD build seem to use the package root as the working directory (no matter where you executed it from), it has to be the case that pkg_path = ".". So it really doesn't make sense to offer pkg_path as a parameter.

So I see three options here:

Use a logical argument for whether or not to pass pkg_path to the reporters in the generated vignette. It's not clear to me what to name or communicate this argument. It's not required for FunctionReporter to be one of the reporters.
Just hard-code to always pass in pkg_path = ".". In principle, it should always work because generally you're only building the vignette as part of the source code of your package. This means people will get test coverage whether they want it or not.
Just don't support the ability to have test coverage for the vignette. We'll figure out how to add it back in later.

For now, I'm going to go with (3) but I'm pretty torn about how to do this. I think this really tells us we should figure out how to make the interface more clear.

jameslamb

This is great Jay! Sorry it took so long to review. Most of my suggestions are minor internal things, but curious to hear what you think about my proposal to make this behave like devtools::document()

DESCRIPTION

R/CreatePackageVignette.R

tests/testthat/test-AbstractPackageReporter.R

tests/testthat/test-CreatePackageVignette.R

vignettes/publishing-reports.Rmd

R/AbstractGraphReporter.R

jameslamb · 2019-03-21T01:14:07Z

R/CreatePackageVignette.R

+#' @importFrom R6 is.R6Class
+#' @importFrom glue glue
+#' @export
+CreatePackageVignette <- function(pkg_name


alright I've been thinking about this...I have an idea we could use to simplify this a bit.

Since the intended use is "run this interactively when you already have the source of the package sitting on your filesystem", I think we should use the same interface as devtools::test(), devtools::document(), and devtools::check() (tools that people are VERY familiar with already). This would look like:

CreatePackageVignette( pkg = ".", pkg_reporters = whatever, vignette_path = whatever )

Benefits this would have:

No new complexity (since we are already parsing the DESCRIPTION file with read.dcf(), we can just get pkg_name from there)

Consistency with existing tools in the R developer ecosystem

Default call becomes CreatePackageVignette() with no args and "just works"

Cut some of the "try to figure out what folder you're in" complexity from the internals

@bburns632 @jayqi what do you think?

I agree that would help simplify the interface. A few potential hiccups I see are:

Do we force the vignette report to always include pkg_path and calculate test coverage?

What if a user did want to create this vignette format without having the source code? Having the source code is not strictly necessarily under my original interface.

Do we worry about the source version diverging from the loaded version? I believe devtools loads the source code for those functions. Do we need to load it too to ensure that there is consistency? FunctionReporter generally has this problem too in other usages, but I feel like we will fail the principle of least astonishment if we don't load the source code, if the main entrypoint is that a user is pointing the function at their package root.

I don't understand how #1 is related to my recommendation.

I'm struggling to come up with a realistic use for "I want to make a vignette but I don't have the package source code". Why would someone who doesn't have the package source code care about making an R vignette instead of just running CreatePackageReport()?

3 is something I hadn't thought of, fair point. I think as long as we document the fact that you have to do devtools::install() or install.packages() or R CMD INSTALL before running this, it's ok. You have to have installed the package already in your current interface, so while I get that it's a concern I don't think it's one that informs whether or not to go with my suggestion.

In every R package I've ever written, I always have an order of steps like this in CI or publishing:

devtools::install()

devtools::document()

R CMD CHECK (also running unit tests`

So I think the "you have to install first" is a tolerable divergence from what devtools::test() etc. do anyway.

I also want to reiterate that the "simplify the interface" benefit of what I'm proposing is nice, but my main reason for proposing this is the "consistency with all the devtools stuff" reason. I think that is a nice way for us to integrate with normal R developer workflows.

Okay @jameslamb, I think what you said all makes sense. I agree that overall the balance is we benefit from having it work with a devtools-style interface.

Is it confusing if this interface is different than CreatePackageReport? Should we name this function something else to make it clear not to expect a similar interface?

I don't think it's confusing to have a different interface for this function

This whole function is tailored for a very specific scenario. I would not think the above is all that confusing, especially since I imagine 90% of the uses will be without parameters.

^ agree with @bburns632

jameslamb

I just re-reviewed. Looking great! I still feel strongly about making the interface look like devtools::stuff() and, in doing that, committing to the fact that this function is intended to be used by package contributors who have the package source code available locally for development.

R/CreatePackageVignette.R

R/AbstractGraphReporter.R

jameslamb · 2019-03-23T21:47:51Z

R/CreatePackageVignette.R

+#' @importFrom R6 is.R6Class
+#' @importFrom glue glue
+#' @export
+CreatePackageVignette <- function(pkg_name


I don't understand how #1 is related to my recommendation.

I'm struggling to come up with a realistic use for "I want to make a vignette but I don't have the package source code". Why would someone who doesn't have the package source code care about making an R vignette instead of just running CreatePackageReport()?

3 is something I hadn't thought of, fair point. I think as long as we document the fact that you have to do devtools::install() or install.packages() or R CMD INSTALL before running this, it's ok. You have to have installed the package already in your current interface, so while I get that it's a concern I don't think it's one that informs whether or not to go with my suggestion.

In every R package I've ever written, I always have an order of steps like this in CI or publishing:

devtools::install()

devtools::document()

R CMD CHECK (also running unit tests`

So I think the "you have to install first" is a tolerable divergence from what devtools::test() etc. do anyway.

I also want to reiterate that the "simplify the interface" benefit of what I'm proposing is nice, but my main reason for proposing this is the "consistency with all the devtools stuff" reason. I think that is a nice way for us to integrate with normal R developer workflows.

tests/testthat/test-CreatePackageVignette.R

bburns632 · 2019-03-27T15:18:06Z

I defer to whatever consensus you two reach on the devtools::stuff() like interface for this function.

jameslamb

I enthusiastically approve. Great work, Jay!

I promise I'll do this for uptasticsearch

bburns632 requested changes Mar 12, 2019

View reviewed changes

jayqi added 5 commits March 13, 2019 17:56

CreatePackageVignette

43d0efd

Added warnings if vignette_path doesn't match pkg_name

dcf9356

Unit tests

ee357b2

Changed default vignette name to use hyphen

bb3e766

Added pkgnet-report vignette

70721ac

jameslamb requested changes Mar 14, 2019

View reviewed changes

jayqi force-pushed the feature/pkg-vignette branch from 36556c6 to 70721ac Compare March 14, 2019 13:16

jayqi commented Mar 14, 2019

View reviewed changes

R/AbstractGraphReporter.R Show resolved Hide resolved

jayqi added 2 commits March 14, 2019 22:15

Vignette section of publishing report vignette

cfc38df

Try changing pkg_path to work with Travis

595637d

Removed pkg_path from CreatePackageVignette

9169f68

jayqi requested review from bburns632 and jameslamb March 15, 2019 04:10

jameslamb requested changes Mar 21, 2019

View reviewed changes

PR review changes

2b4f4c4

jameslamb requested changes Mar 23, 2019

View reviewed changes

Added pkgnet gallery to publishing vignette

37e2515

bburns632 approved these changes Mar 27, 2019

View reviewed changes

jayqi added 2 commits March 27, 2019 18:54

CreatePackageVignette to follow devtools interface convention

25b16ae

Updated publishing vignette with new interface

a1e96ac

jayqi requested a review from jameslamb March 28, 2019 02:27

jameslamb approved these changes Mar 28, 2019

View reviewed changes

jameslamb mentioned this pull request Mar 28, 2019

Add a pkgnet vignette uptake/uptasticsearch#147

Open

jayqi merged commit f6a01f5 into uptake:master Mar 28, 2019

jayqi deleted the feature/pkg-vignette branch March 28, 2019 21:58

jayqi mentioned this pull request Mar 29, 2019

Include pkgnet's own package report as vignette and/or pkgdown article #159

Closed

jayqi added this to the Release v0.4.0 milestone Mar 29, 2019

jameslamb mentioned this pull request Apr 28, 2019

#16 Package score ( health) implementation idea #116

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CreatePackageVignette function #200

CreatePackageVignette function #200

jayqi commented Mar 11, 2019 •

edited

Loading

codecov-io commented Mar 11, 2019 •

edited

Loading

bburns632 left a comment

jameslamb left a comment

jayqi commented Mar 15, 2019 •

edited

Loading

jameslamb left a comment

jameslamb Mar 21, 2019

jayqi Mar 23, 2019

jameslamb Mar 23, 2019

jayqi Mar 23, 2019

jameslamb Mar 27, 2019

bburns632 Mar 27, 2019

jameslamb Mar 27, 2019

jameslamb left a comment

jameslamb Mar 23, 2019

bburns632 commented Mar 27, 2019 •

edited

Loading

jameslamb left a comment

CreatePackageVignette function #200

CreatePackageVignette function #200

Conversation

jayqi commented Mar 11, 2019 • edited Loading

codecov-io commented Mar 11, 2019 • edited Loading

Codecov Report

bburns632 left a comment

Choose a reason for hiding this comment

jameslamb left a comment

Choose a reason for hiding this comment

jayqi commented Mar 15, 2019 • edited Loading

jameslamb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jameslamb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bburns632 commented Mar 27, 2019 • edited Loading

jameslamb left a comment

Choose a reason for hiding this comment

jayqi commented Mar 11, 2019 •

edited

Loading

codecov-io commented Mar 11, 2019 •

edited

Loading

jayqi commented Mar 15, 2019 •

edited

Loading

bburns632 commented Mar 27, 2019 •

edited

Loading