Split the User guide, add chapters for CDI and Examples, fix #415

docs/modules/ROOT/nav.adoc

@@ -1,3 +1,6 @@
 * xref:user-guide.adoc[User guide]
+** xref:first-steps.adoc[First steps]
+** xref:cdi.adoc[CDI]
+** xref:examples.adoc[Examples]
 * xref:contributor-guide.adoc[Contributor guide]
 * xref:list-of-camel-quarkus-extensions.adoc[List of Camel Quarkus extensions]

docs/modules/ROOT/pages/cdi.adoc

@@ -0,0 +1,41 @@
+= Contexts and Dependency Injection (CDI) in Camel Quarkus
+
+CDI plays a central role in Quarkus and Camel Quarkus offers a first class support for it too.
+
+You may use `@Inject`, `@ConfigProperty` and similar annotations e.g. to inject beans and configuration values to
+your Camel `RouteBuilder`s. Here is the `RouteBuilder` from our `timer-log-cdi` xref:examples.adoc[example]:
+
+[source,java]
+----
+import javax.enterprise.context.ApplicationScoped;
+import javax.inject.Inject;
+import org.apache.camel.builder.RouteBuilder;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+@ApplicationScoped <1>
+public class TimerRoute extends RouteBuilder {
+
+    @ConfigProperty(name = "timer.period", defaultValue = "1s") <2>
+    String period;
+
+    @Inject
+    Counter counter;
+
+    @Override
+    public void configure() throws Exception {
+        fromF("timer:foo?period=%s", period)
+                .setBody(() -> "Incremented the counter: " + counter.increment())
+                .to("log:cdi-example?showExchangePattern=false&showBodyType=false");
+    }
+}
+----
+
+<1> The `@ApplicationScoped` annotation is required for `@Inject` and `@ConfigProperty` to work in a `RouteBuilder`.
+Note that the `@ApplicationScoped` beans are managed by the CDI container and their life cycle is thus a bit more
+complex than the one of the plain `RouteBuilder`. In other words, using `@ApplicationScoped` in `RouteBuilder`s comes
+with some boot time penalty and you should therefore only annotate your `RouteBuilder` with `@ApplicationScoped` when
+you really need it.
+
+<2> The value for the `timer.period` property is defined in `src/main/resources/application.properties` of the example project.
+
+TIP: Please refer to the https://quarkus.io/blog/quarkus-dependency-injection[Quarkus Dependency Injection guide] for more details.

docs/modules/ROOT/pages/examples.adoc

@@ -0,0 +1,4 @@
+= Camel Quarkus Examples
+
+We offer several examples in our https://github.com/apache/camel-quarkus/tree/master/examples[source tree]. To learn
+how to use them, please follow the xref:first-steps.adoc[First steps] chapter of the User guide.

docs/modules/ROOT/pages/first-steps.adoc

@@ -0,0 +1,201 @@
+== First steps
+
+We recommend you to choose an example from our https://github.com/apache/camel-quarkus/tree/master/examples[source tree]
+as a base for your real world project.
+
+=== Prerequisites
+
+* A `git` client
+* An IDE
+* JDK 1.8+ with JAVA_HOME configured appropriately
+* Apache Maven 3.5.3+
+* GraalVM with `native-image` command installed and `GRAALVM_HOME` environment variable set, see
+  https://quarkus.io/guides/building-native-image-guide[Building a native executable] section of the Quarkus
+  documentation.
+* If your are on Linux, `docker` is sufficient for the native mode too. Use `-Pnative,docker` instead of `-Pnative`
+  if you choose this option.
+
+=== Step by step with the `rest-json` example
+
+1. Clone Camel Quarkus and checkout the latest release tag
++
+[source,shell]
+----
+$ git clone https://github.com/apache/camel-quarkus.git
+$ cd camel-quarkus
+# checkout the latest tag
+$ git checkout $(git describe --abbrev=0)
+----
+
+2. Copy the `rest-json` example out of the Camel Quarkus source tree.
++
+[source,shell]
+----
+$ cd ..
+$ cp -r camel-quarkus/examples/rest-json .
+$ cd rest-json
+----
+
+3. Open the `pom.xml` file in your IDE.
++
+Make sure that the parent is `org.apache.camel.quarkus:camel-quarkus-bom` and do the changes as
+sketched below:
++
+[source,xml,subs="attributes+"]
+----
+<project>
+    <parent>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-bom</artifactId><!--1-->
+        <version>{camel-quarkus-last-release}</version>
+        <!-- <relativePath>../../bom/pom.xml</relativePath> --><!--2-->
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>org.my-org</groupId><!--3-->
+    <artifactId>my-app</artifactId><!--4-->
+    <version>0.0.1-SNAPSHOT</version><!--5-->
+
+    ...
+
+</project>
+----
+<1> Change the `<artifactId>` element to `camel-quarkus-bom`.
+<2> Remove the `<relativePath>` element.
+<3> Add a `groupId` of your choice.
+<4> Change the `artifactId` to whatever you like
+<5> Add the `version`
+
+=== Explore the application code
+
+The application has just two compile dependencies:
+
+[source,xml,subs="attributes+"]
+----
+<dependency>
+    <groupId>org.apache.camel.quarkus</groupId>
+    <artifactId>camel-quarkus-platform-http</artifactId>
+</dependency>
+<dependency>
+    <groupId>org.apache.camel</groupId>
+    <artifactId>camel-jackson</artifactId>
+</dependency>
+----
+
+They are managed in `camel-quarkus-bom` that we use as the Maven parent. `camel-quarkus-bom` and its ancestors also
+manage plugins necessary for a typical Camel Quarkus application. In case you cannot use `camel-quarkus-bom` as a
+parent of your application, make sure that you add those plugins manually.
+
+There are only three classes in the application: `Routes` defining the Camel routes and a couple of entity classes
+(`Fruit` and `Legume`).
+
+`src/main/resources/application.properties` configure the application. E.g. the `camel.context.name` is set there.
+
+=== Development mode
+
+[source,shell]
+----
+$ mvn clean compile quarkus:dev
+----
+
+This command compiles the project, starts your application and lets the Quarkus tooling watch for changes in your
+workspace. Any modifications in your project will automatically take effect in the running application.
+
+Check the application in the browser, e.g. http://localhost:8080/fruits[http://localhost:8080/fruits]
+for the `rest-json` example
+
+Then change something in the code and see the changes applied by refreshing the browser.
+
+Please refer to https://quarkus.io/guides/maven-tooling#development-mode[Quarkus documentation] for more details.
+
+
+=== Testing
+
+There are two test classes in our example: `RestJsonTest` is for the JVM mode while `RestJsonIT` is there for the native
+mode.
+
+The JVM mode tests are run by `maven-surefire-plugin` in the `test` Maven phase:
+
+[source,shell]
+----
+$ mvn clean test
+----
+
+This should take about 15 seconds.
+
+The native mode tests are verified by `maven-failsafe-plugin` in the `verify` phase. Pass the `native` property to
+activate the profile that runs them:
+
+[source,shell]
+----
+$ mvn clean verify -Pnative
+----
+
+This takes about 2.5 minutes (once you have all dependencies cached).
+
+=== Package and run the application
+
+==== JVM mode
+
+`mvn package` prepares a thin `jar` for running on a stock JVM:
+
+[source,shell]
+----
+$ mvn clean package
+$ ls -lh target
+...
+-rw-r--r--. 1 ppalaga ppalaga 238K Oct 11 18:55  my-app-0.0.1-SNAPSHOT-runner.jar
+...
+----
+
+You can run it as follows:
+
+[source,shell]
+----
+$ java -jar target/*-runner.jar
+...
+[io.quarkus] (main) Quarkus 0.23.2 started in 1.163s. Listening on: http://[::]:8080
+----
+
+Notice the boot time around a second.
+
+The thin `jar` contains just the application code. To run it, the dependencies in `target/lib` are required too.
+
+==== Native mode
+
+To prepare a native executable using GraalVM, run the following command:
+
+[source,shell]
+----
+$ mvn clean package -Pnative
+$ ls -lh target
+...
+-rwxr-xr-x. 1 ppalaga ppalaga  46M Oct 11 18:57  my-app-0.0.1-SNAPSHOT-runner
+...
+----
+
+Note that the `runner` in the listing above has no `.jar` extension and has the `x` (executable) permission set. Thus
+it can be run directly:
+
+[source,shell]
+----
+$ ./target/*-runner
+...
+[io.quarkus] (main) Quarkus 0.23.2 started in 0.013s. Listening on: http://[::]:8080
+...
+----
+
+Check how fast it started and check how little memory it consumes:
+
+[source,shell]
+----
+$ ps -o rss,command -p $(pgrep my-app)
+  RSS COMMAND
+34916 ./target/my-app-0.0.1-SNAPSHOT-runner
+----
+
+That's under 35 MB of RAM!
+
+TIP: https://quarkus.io/guides/building-native-image-guide.html[Quarkus Native executable quide] contains more details
+including
+https://quarkus.io/guides/building-native-image-guide.html#creating-a-container[steps for creating a container image].