Docs: copy example src from integration tests

.github/workflows/doc-build.yml

@@ -52,7 +52,8 @@ jobs:
           key: q2maven-doc-${{ steps.get-date.outputs.date }}
       - name: Build
         run: |
-          ./mvnw -Dquickly-ci -B --settings .github/mvn-settings.xml install
+          ./mvnw -Dquickly-ci -B -DskipDocs=false --settings .github/mvn-settings.xml install
+
       - name: Build Docs
         run: |
           ./mvnw -e -B --settings .github/mvn-settings.xml clean org.asciidoctor:asciidoctor-maven-plugin:process-asciidoc -pl docs -Ddocumentation-pdf

docs/pom.xml

@@ -23,6 +23,7 @@
         <quarkus-home-url>https://quarkus.io</quarkus-home-url>
         <quarkus-base-url>https://github.com/quarkusio/quarkus</quarkus-base-url>
         <quickstarts-base-url>https://github.com/quarkusio/quarkus-quickstarts</quickstarts-base-url>
+        <code-example-dir>${project.basedir}/../target/asciidoc/examples</code-example-dir>
     </properties>
 
     <name>Quarkus - Documentation</name>
@@ -2794,6 +2795,25 @@
                             </environmentVariables>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>copy-tagged-java-source</id>
+                        <phase>process-classes</phase>
+                        <goals>
+                            <goal>java</goal>
+                        </goals>
+                        <configuration>
+                            <skip>${skipDocs}</skip>
+                            <mainClass>io.quarkus.docs.generation.CopyExampleSource</mainClass>
+                            <arguments>
+                                <argument>${code-example-dir}</argument>
+                                <argument>${project.basedir}/..</argument>
+                                <argument>${project.basedir}/src/main/asciidoc</argument>
+                            </arguments>
+                            <environmentVariables>
+                                <MAVEN_CMD_LINE_ARGS>${env.MAVEN_CMD_LINE_ARGS}</MAVEN_CMD_LINE_ARGS>
+                            </environmentVariables>
+                        </configuration>
+                    </execution>
                     <execution>
                         <id>generate-doc-manifests</id>
                         <phase>prepare-package</phase>
@@ -2830,6 +2850,7 @@
                     <preserveDirectories>true</preserveDirectories>
                     <attributes>
                         <generated-dir>${project.basedir}/../target/asciidoc/generated</generated-dir>
+                        <code-examples>${code-example-dir}</code-examples>
                         <imagesdir>./images</imagesdir>
                         <icons>font</icons>
                         <sectanchors>true</sectanchors>
@@ -2912,7 +2933,7 @@
                         <neo4j-guide>https://quarkiverse.github.io/quarkiverse-docs/quarkus-neo4j/dev/index.html</neo4j-guide>
                         <vault-guide>https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/index.html</vault-guide>
                         <vault-datasource-guide>https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/vault-datasource.html</vault-datasource-guide>
-                        <micrometer-registry-gulde>https://quarkiverse.github.io/quarkiverse-docs/quarkus-micrometer-registry/dev/</micrometer-registry-gulde>
+                        <micrometer-registry-guide>https://quarkiverse.github.io/quarkiverse-docs/quarkus-micrometer-registry/dev/</micrometer-registry-guide>
                     </attributes>
                 </configuration>
                 <executions>

docs/src/main/asciidoc/_examples/attributes.adoc

@@ -3,8 +3,9 @@
 :idprefix:
 :idseparator: -
 :icons: font
+:code-examples: ../../../../../target/asciidoc/examples
 :doc-guides: ..
 :doc-examples: .
 :imagesdir: ./images
 :includes: ../includes
-:root: ../../asciidoc
+

docs/src/main/asciidoc/_templates/attributes.adoc

@@ -3,8 +3,8 @@
 :idprefix:
 :idseparator: -
 :icons: font
+:code-examples: ../../../../../target/asciidoc/examples
 :doc-guides: ..
 :doc-examples: ../_examples
-:imagesdir: ../../asciidoc/images
+:imagesdir: ../images
 :includes: ../includes
-:root: ../../asciidoc/

docs/src/main/asciidoc/attributes.adoc

@@ -4,8 +4,8 @@
 :idprefix:
 :idseparator: -
 :icons: font
-// tag::xref-attributes[]
+:code-examples: ../../../../target/asciidoc/examples
+:doc-guides: ./
 :doc-examples: ./_examples
 :imagesdir: ./images
 :includes: ./includes
-// end::xref-attributes[]

docs/src/main/asciidoc/doc-reference.adoc

@@ -23,10 +23,10 @@ The Asciidoc files can be found in the `src/main/asciidoc` directory within the
 
 Create new documentation files using the appropriate template for the content type: 
 
-Concepts:: Use `src/main/asciidoc/_templates/template-concepts.adoc`
-How-To Guides:: Use `src/main/asciidoc/_templates/template-howto.adoc`
-Reference:: Use `src/main/asciidoc/_templates/template-reference.adoc`
-Tutorials:: Use `src/main/asciidoc/_templates/template-tutorial.adoc`
+Concepts:: Use `docs/src/main/asciidoc/_templates/template-concepts.adoc`
+How-To Guides:: Use `docs/src/main/asciidoc/_templates/template-howto.adoc`
+Reference:: Use `docs/src/main/asciidoc/_templates/template-reference.adoc`
+Tutorials:: Use `docs/src/main/asciidoc/_templates/template-tutorial.adoc`
 
 == Output locations
 
@@ -183,10 +183,16 @@ Quarkus documentation is built from source in a few different environments.
 We use attributes in our cross-references to ensure our docs can be built across these environments.
 
 .Cross-reference source attributes
-[source,asciidoc]
-----
-include::attributes.adoc[tag=xref-attributes]
-----
+[cols="<m,<2",options="header"]
+|===
+|Attribute|Description
+|\{code-examples}|Relative path to directory containing collected example source files
+|\{doc-guides}|Relative path to documentation adoc files (e.g. doc-concepts.adoc)
+|\{doc-examples}|Relative path to source examples for documentation guides
+|\{generated-dir}|Relative path to generated configuration `*.adoc` files
+|\{imagesdir}|Relative path to directory containing images
+|\{includes}|Relative path to directory containing partial/reusable content (`*.adoc` files)
+|===
 
 When cross-referencing content, always use the inter-document `xref:` syntax and supply a human-readable label to your link.
 
@@ -195,13 +201,75 @@ When cross-referencing content, always use the inter-document `xref:` syntax and
 ----
 xref:{doc-guides}/doc-concepts.adoc[Quarkus Documentation concepts] <1>
 ----
-<1> The cross reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`
+<1> The cross reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`.
+
+=== Reference source code 
+
+There are many ways to include source code and examples in documentation.
+
+The simplest is to write it directly in the file, like this:
+
+[source,asciidoc]
+-----
+[source,java]
+----
+System.out.println("Hello, World!");
+----
+-----
+
+In documents like tutorials, you may want to reference source code that is built and tested regularly.
+The Quarkus documentation module build will copy source files enumerated in `*-examples/yaml` files into a flattened structure in the `target/asciidoc/examples` directory (from the project root).
+
+[source,yaml]
+----
+examples:
+- source: path/to/source/file/SomeClassFile.java <1>
+  target: prefix-simplified-unique-filename.java <2>
+----
 
-=== Variables for use in documents
+<1> define the path of source to be copied
+<2> define the simplified target file name to use when copying the file into the `target/asciidoc/examples` directory. We recommend using the same prefix as the related/consuming documentation in the file name.
 
-The following variables externalize key information that can change over time, and so references
-to such information should be done by using the variable inside of {} curly brackets. The
-complete list of externalized variables for use is given in the following table:
+Content copied in this way is referenced using the `\{code-examples}` source attribute. If a copied file contains the literal string `{{source}}`, that literal value is replaced with the path of the source file.
+
+.Micrometer example
+* The source file to be copied is:
++
+`integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java`
+
+* The target file name we want to use in docs is:
++
+`telemetry-micrometer-tutorial-example-resource.java`.
+
+* The source and target file names are declared in `docs/src/main/asciidoc/telemetry-examples.yaml`: 
++
+[source,yaml]
+----
+examples:
+- source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
+  target: telemetry-micrometer-tutorial-example-resource.java
+----
+
+* Snippets from this source file are then included using the following path:
++
+`\{code-examples}/telemetry-micrometer-tutorial-example-resource.java`.
+* The source file contains the following comment: 
+[source,java]
+----
+// Source: {{source}}
+----
+* The copied file contains this comment instead: 
+[source,java]
+----
+// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
+----
+
+=== Quarkus documentation variables
+
+The following variables externalize key information that can change over time. References
+to such information should use the variable inside of curly brackets, `{}`. 
+
+The complete list of externalized variables for use is given in the following table:
 
 .Variables
 [cols="<m,<m,<2",options="header"]
@@ -232,4 +300,5 @@ complete list of externalized variables for use is given in the following table:
 
 |\{graalvm-version}|{graalvm-version}| Recommended GraalVM version to use.
 |\{graalvm-flavor}|{graalvm-flavor}| The full flavor of GraalVM to use e.g. `19.3.1-java11`. Make sure to use a `java11` version.
-|===
+|===
+

docs/src/main/asciidoc/telemetry-examples.yaml

@@ -0,0 +1,3 @@
+examples:
+- source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
+  target: telemetry-micrometer-tutorial-example-resource.java