Restore @DocumentExamples in the docs either through RewriteRecipeExamplesPlugin or alternative

[timtebeek]

What problem are you trying to solve?

RewriteRecipeExamplesPlugin was disabed in dec3f04 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

• Missing document examples for some recipes rewrite-docs#210
• Change Type recipe now shows a Kotlin example only rewrite-docs#211
• dec3f04

[knutwannheden]

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]

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]

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]

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

• Add test examples to docs again rewrite-recipe-markdown-generator#74 (comment)