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

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building 2be5658f9163bbaa28772411710b75b48edcb53a

Status	Name	Step	Failures	Logs	Raw logs
✖	JVM Tests - JDK 11	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 17	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 18	Build	Failures	Logs	Raw logs
✖	Native Tests - Misc4	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

:gear: JVM Tests - JDK 11 #

- Failing: integration-tests/micrometer-prometheus 

:package: integration-tests/micrometer-prometheus

✖ io.quarkus.it.micrometer.prometheus.ExampleResourcesTest.testTimerExample line 56 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Response body doesn't match expectation.

---

:gear: JVM Tests - JDK 11 Windows #

- Failing: integration-tests/micrometer-prometheus 

:package: integration-tests/micrometer-prometheus

✖ io.quarkus.it.micrometer.prometheus.ExampleResourcesTest.testTimerExample line 56 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Response body doesn't match expectation.

---

:gear: JVM Tests - JDK 17 #

- Failing: integration-tests/micrometer-prometheus 

:package: integration-tests/micrometer-prometheus

✖ io.quarkus.it.micrometer.prometheus.ExampleResourcesTest.testTimerExample line 56 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Response body doesn't match expectation.

---

:gear: JVM Tests - JDK 18 #

- Failing: integration-tests/micrometer-prometheus 

:package: integration-tests/micrometer-prometheus

✖ io.quarkus.it.micrometer.prometheus.ExampleResourcesTest.testTimerExample line 56 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Response body doesn't match expectation.

---

:gear: Native Tests - Misc4 #

- Failing: integration-tests/micrometer-prometheus 

:package: integration-tests/micrometer-prometheus

✖ io.quarkus.it.micrometer.prometheus.ExampleResourcesIT.testTimerExample - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Response body doesn't match expectation.

[ebullient]

Bugger. Will fix on Monday. Traveling now.

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building b83eb8e8795edc26358845ec808a833b5e31b0a4

Status	Name	Step	Failures	Logs	Raw logs
:heavy_check_mark:	JVM Tests - JDK 11
:heavy_check_mark:	JVM Tests - JDK 17
✖	JVM Tests - JDK 18	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

:gear: JVM Tests - JDK 18 #

- Failing: extensions/smallrye-reactive-messaging-kafka/deployment 
! Skipped: integration-tests/kafka-oauth-keycloak integration-tests/kafka-sasl-elytron integration-tests/kubernetes/quarkus-standard-way-kafka and 3 more

:package: extensions/smallrye-reactive-messaging-kafka/deployment

✖ io.quarkus.smallrye.reactivemessaging.kafka.deployment.testing.KafkaDevServicesContinuousTestingWorkingAppPropsTestCase.testContinuousTestingScenario3 line 54 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Failed to wait for test run 4 State{lastRun=3, running=true, inProgress=true, run=1, passed=0, failed=1, skipped=0, isBrokenOnly=false, isTestOutput=false, isInstrumentationBasedReload=false, isLiveReload=true}
	at io.quarkus.test.ContinuousTestingTestUtils.waitForNextCompletion(ContinuousTestingTestUtils.java:44)
	at io.quarkus.smallrye.reactivemessaging.kafka.deployment.testing.KafkaDevServicesContinuousTestingWorkingAppPropsTestCase.testContinuousTestingScenario3(KafkaDevServicesContinuousTestingWorkingAppPropsTestCase.java:54)

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building c5cbc45fe113c8948f2aa4294bbd1a0ee8083bb2

Status	Name	Step	Failures	Logs	Raw logs
✖	Gradle Tests - JDK 11	Build	Failures	Logs	Raw logs
:heavy_check_mark:	Gradle Tests - JDK 11 Windows
✖	JVM Tests - JDK 11	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 17	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 18	Build	Failures	Logs	Raw logs
✖	Native Tests - HTTP	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

:gear: Gradle Tests - JDK 11 #

- Failing: integration-tests/gradle 

:package: integration-tests/gradle

✖ io.quarkus.gradle.devmode.CompositeBuildWithDependenciesDevModeTest.main line 24 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with lambda expression in io.quarkus.test.devmode.util.DevModeTestUtils that uses java.util.function.Supplier, java.util.function.Supplierjava.util.concurrent.atomic.AtomicReference, java.util.concurrent.atomic.AtomicReferencejava.lang.String, java.lang.Stringboolean was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

---

:gear: JVM Tests - JDK 11 #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: JVM Tests - JDK 11 Windows #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: JVM Tests - JDK 17 #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: JVM Tests - JDK 18 #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: Native Tests - HTTP #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedITCase.should_accept_self_signed_certs - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedITCase.should_accept_self_signed_certs_java_url - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllIT.restClient - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostIT.restClient - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

[quarkus-bot[bot]]

---

:waning_crescent_moon: This workflow status is outdated as a new workflow run has been triggered.

---

Failing Jobs - Building b8bae89b0d6711da53141f6cd11f7e0dec79e282

Status	Name	Step	Failures	Logs	Raw logs
✖	Gradle Tests - JDK 11	Build	Failures	Logs	Raw logs
:heavy_check_mark:	Gradle Tests - JDK 11 Windows
✖	JVM Tests - JDK 11	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 11 Windows	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 17	Build	Failures	Logs	Raw logs
✖	JVM Tests - JDK 18	Build	Failures	Logs	Raw logs
✖	Native Tests - HTTP	Build	Failures	Logs	Raw logs

Full information is available in the Build summary check run.

Failures

:gear: Gradle Tests - JDK 11 #

- Failing: integration-tests/gradle 

:package: integration-tests/gradle

✖ io.quarkus.gradle.devmode.CompositeBuildWithDependenciesDevModeTest.main line 24 - More details - Source on GitHub

org.awaitility.core.ConditionTimeoutException: Condition with lambda expression in io.quarkus.test.devmode.util.DevModeTestUtils that uses java.util.function.Supplier, java.util.function.Supplierjava.util.concurrent.atomic.AtomicReference, java.util.concurrent.atomic.AtomicReferencejava.lang.String, java.lang.Stringboolean was not fulfilled within 1 minutes.
	at org.awaitility.core.ConditionAwaiter.await(ConditionAwaiter.java:167)
	at org.awaitility.core.CallableCondition.await(CallableCondition.java:78)

---

:gear: JVM Tests - JDK 11 #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: JVM Tests - JDK 11 Windows #

- Failing: integration-tests/opentelemetry-vertx integration-tests/rest-client 

:package: integration-tests/opentelemetry-vertx

✖ io.quarkus.it.opentelemetry.vertx.HelloRouterTest.bus line 134 - More details - Source on GitHub

org.opentest4j.AssertionFailedError: expected: <CONSUMER> but was: <PRODUCER>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:151)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: JVM Tests - JDK 17 #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: JVM Tests - JDK 18 #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedTestCase.should_accept_self_signed_certs_java_url line 29 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllTestCase.restClient line 20 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostTestCase.restClient line 22 - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

---

:gear: Native Tests - HTTP #

- Failing: integration-tests/rest-client 

:package: integration-tests/rest-client

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedITCase.should_accept_self_signed_certs - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.selfsigned.ExternalSelfSignedITCase.should_accept_self_signed_certs_java_url - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.trustall.ExternalTlsTrustAllIT.restClient - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.

✖ io.quarkus.it.rest.client.wronghost.ExternalWrongHostIT.restClient - More details - Source on GitHub

java.lang.AssertionError: 
1 expectation failed.
Expected status code <200> but was <500>.