search

openrewrite / rewrite-build-gradle-plugin

Common build logic for building OpenRewrite and recipe jars.
Apache License 2.0
4 stars 5 forks source link

Restore `@DocumentExamples` in the docs either through `RewriteRecipeExamplesPlugin` or alternative #20

Closed timtebeek closed 2 weeks ago

timtebeek commented 1 year ago

What problem are you trying to solve?

RewriteRecipeExamplesPlugin was disabed in https://github.com/openrewrite/rewrite-build-gradle-plugin/commit/dec3f046e56d03f4dd7a8f12813ec7f1e3ddeb14 at the time when some recipes produced invalid yaml(?). Not exactly clear what circumstances lead to disabling the plugin; not ideal to retry without that context.

Describe the solution you'd like

Would like to see the examples restored in the docs and on the platform, as the @DocumentExample cases help visualize what effect a recipe has, in addition to the name and description.

Have you considered any alternatives or workarounds?

We might call the ExamplesExtractor (or similar) from rewrite-recipe-markdown-generator, such that there's no risk of tripping up the platform with invalid Yaml resources.

Additional context

knutwannheden commented 1 year ago

I believe one problem was that it caused CI builds to be extremely slow or even time out in some repos (rewrite-cobol if I am not mistaken). @jkschneider or @sambsnyd will know more. Please verify that first again. Otherwise we could provide an explicit opt-in or opt-out property.

timtebeek commented 1 year ago

Discussed internally as well. Main points copied here.

S: We should disable that at least until we can support lombok in the java parser. The more lombok we use the more missing type information, the slower java parsing goes. O: maybe we disable it across the board. it fits more with docs generation or some on demand task that in the main build

timtebeek commented 1 year ago

So as discussed on the stand up: we can potentially move this to rewrite-recipe-markdown-generator. The steps there are roughly:

  1. Pull over the RecipeExamplesTask method that extracts examples to RRMG; should not need any dependency on Gradle there; we're only interested in how it executes a recipe using a JavaParser, and the underlying ExamplesExtractor it uses.
  2. the RRMG task needs access to the source code of the individual OpenRewrite modules. One way to do that would be to download those from Maven Central, where we also publish -sources.jar files. These can be extracted as regular tar files, to get access to the sources.
  3. The output of the RRMG us currently Yaml files; we likely have some flexibility there in getting those merged into the actual docs. Not sure if GitBook allows you to include files from elsewhere, but that could be easiest. Otherwise it'd be a lookup per recipe if we have a corresponding Yaml recipe example.

That's very high over; there may be specifics or alternatives that I haven't thought of yet, but figured write this down such that Mike can challenge that.

Again, this would only make those docs available on docs.openrewrite.org; unless we're able to fix the performance issues with the RewriteRecipeExamplesPlugin we had before, which we're unlikely to attempt now given the potential impact on run durations.

Alternatively we can only run the existing plugin when we for instance publish a release; but then still there's negative effects on getting a timely release out.

timtebeek commented 2 weeks ago

Closing as a duplicate, with alternative approach listed here which does not require examples to be bundled.