Docs: copy example src from integration tests

[ebullient]

Add a new build tool that copies source files located in a specific package from the integration-tests directory (where they are continuously built/tested) into a source directory that can be used for tagged inclusion in docs.

As an example (included in the commit):

• Integration test source:
  integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java

• is copied to (flattened file structure):
  target/asciidoc/examples/telemetry-micrometer-tutorial-ExampleResource.java.

• and referenced as:
  {code-examples}/telemetry-micrometer-tutorial-ExampleResource.java.

(Aside: The telemetry- prefix is a step towards revisions to telemetry docs).

[maxandersen]

so I gave this a few thoughts and I don't grok why we would want to separate the source from the docs nor mix in examples with the integration tests. Its not an approach that scales well imo; especially when we start thinking quarkiverse extension having docs that lives outside the core repo.

Why not have the sources next to the docs and just add a ci run that includes running those tests?

[ebullient]

Why not have the sources next to the docs and just add a ci run that includes running those tests?

Because the dependency combinations will keep growing over time. There are two things that we want: We want to use source in docs that has been compiled/tested, and we want to understand how well our code generally is tested (and this falls roughly in that bucket, even though it is a constrained/specific path).

I've had this micrometer example in integration tests for micrometer for a long time to make sure I didn't regress anything and ensure the example continued to work (it is sadly duplicated in the quickstart, but the quickstarts are a different problem, and in this case, would want the final version w/o the tags).

So I think putting all of the code with the docs is worse from a build perspective (deps will grow, and we will run into problems with exclusive extensions.. like smallrye metrics and micrometer). Integration tests are a better place than deployment tests because of structure and how they are run...

[ebullient]

To avoid duplicate file names when making copies (for further/later propagation), @maxandersen and I discussed using files to specify the list of files to copy rather than trying to auto-detect. This also means I can support any file from anywhere in the Quarkus project.

Current idea (not final) is a yaml file with a format like this:

examples:
- source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
  target: telemetry-micrometer-tutorial-example-resource.java

We can have as many of these as we want. e.g. I might name the file containing the above with a prefix so it stays with/near the docs about micrometer..

Files are still copied into the specified examples dir, so referencing the file in docs would effectively look like {code-example}/<value of target specified in yaml>.

Given the above example, I would reference that in a tutorial like so:

include::{code-examples}/telemetry-micrometer-tutorial-example-resource.java[]

Tool provides some indication of what is being read/copied (anything -examples.yaml from the source directory specified in the build:

[INFO] --- exec-maven-plugin:3.0.0:java (copy-tagged-java-source) @ quarkus-documentation ---
[INFO] Output directory: /Users/ebullient/git/quarkusio/quarkus/target/asciidoc/examples
[INFO] Project root: /Users/ebullient/git/quarkusio/quarkus
[INFO] Reading: /Users/ebullient/git/quarkusio/quarkus/docs/src/main/asciidoc/telemetry-examples.yaml
[INFO] Copied integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
           to /Users/ebullient/git/quarkusio/quarkus/target/asciidoc/examples/telemetry-micrometer-tutorial-example-resource.java

[maxandersen]

@ebullient approach looks like we dicussed so part is fine.

What i'm missing is what are the steps to actually now edit the docs?

before git clone was enough, preview worked fine in my editor.

Now I have to run some command first to have the target dir created....what command would that actually be ?

[ebullient]

No additional commands are required.

-DquicklyDocs and/or build the docs module will be enough. The fetch/copy of source happens right alongside the generation of config files, which is part of the docs module build

[ebullient]

Bugger. Will fix on Monday. Traveling now.

[maxandersen]

updated approach where docs are referenced explicitly is good! lgtm.