You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by nf...@apache.org on 2018/12/14 08:07:37 UTC
[camel-k] 05/08: Initial work for Antora
This is an automated email from the ASF dual-hosted git repository.
nferraro pushed a commit to branch antora
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 6af1f5b12b0fefd2a5752ba6c3a1dca591c370d9
Author: nferraro <ni...@gmail.com>
AuthorDate: Wed Dec 12 09:58:38 2018 +0100
Initial work for Antora
---
README.adoc | 2 +-
docs/antora.yml | 5 ++
docs/cluster-setup.adoc | 47 -----------------
docs/modules/ROOT/nav.adoc | 6 +++
.../modules/ROOT/pages/configuration/index.adoc | 61 +---------------------
docs/{ => modules/ROOT/pages}/developers.adoc | 0
docs/modules/ROOT/pages/index.adoc | 27 ++++++++++
.../ROOT/pages/installation/gke.adoc} | 10 ++--
docs/modules/ROOT/pages/installation/index.adoc | 40 ++++++++++++++
docs/modules/ROOT/pages/installation/minikube.adoc | 19 +++++++
.../modules/ROOT/pages/installation/minishift.adoc | 21 ++++++++
docs/{ => modules/ROOT/pages}/languages.adoc | 0
.../modules/ROOT/pages/running.adoc | 54 +++----------------
docs/{ => modules/ROOT/pages}/traits.adoc | 0
14 files changed, 133 insertions(+), 159 deletions(-)
diff --git a/README.adoc b/README.adoc
index 91790ec..cd0ea3f 100644
--- a/README.adoc
+++ b/README.adoc
@@ -7,7 +7,7 @@ image:https://godoc.org/github.com/apache/camel-k?status.svg["GoDoc", link="http
image:https://img.shields.io/github/license/openshift/origin.svg?maxAge=2592000["Licensed under Apache License version 2.0", link="https://www.apache.org/licenses/LICENSE-2.0"]
image:https://badges.gitter.im/apache/camel-k.png["Chat on Gitter", link="https://gitter.im/apache/camel-k"]
-Apache Camel K (a.k.a. Kamel) is a lightweight integration framework built from Apache Camel that runs natively on Kubernetes and is specifically designed for serverless and microservice architectures.
+Apache Camel K is a lightweight integration framework built from Apache Camel that runs natively on Kubernetes and is specifically designed for serverless and microservice architectures.
[[getting-started]]
== Getting Started
diff --git a/docs/antora.yml b/docs/antora.yml
new file mode 100644
index 0000000..2b7af22
--- /dev/null
+++ b/docs/antora.yml
@@ -0,0 +1,5 @@
+name: camel-k
+title: Apache Camel K
+version: latest
+nav:
+- modules/ROOT/nav.adoc
\ No newline at end of file
diff --git a/docs/cluster-setup.adoc b/docs/cluster-setup.adoc
deleted file mode 100644
index ef38dd6..0000000
--- a/docs/cluster-setup.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[creating-cluster]]
-Creating a Development Cluster
-==============================
-
-There are various options for creating a development cluster:
-
-[[minishift]]
-== Minishift
-
-You can run Camel K integrations on OpenShift using the Minishift cluster creation tool.
-Follow the instructions in the https://github.com/minishift/minishift#getting-started[getting started guide] for the installation.
-
-After installing the `minishift` binary, you need to enable the `admin-user` addon:
-
-```
-minishift addons enable admin-user
-```
-
-NOTE: the admin user addon should be enabled before starting the cluster for the first time
-
-Then you can start the cluster with:
-
-```
-minishift start
-```
-
-You can now proceed to link:/README.adoc[install Camel K].
-
-[[minikube]]
-== Minikube
-
-You can run Camel K integrations on plain Kubernetes using the Minikube cluster creation tool.
-Follow the instructions in the https://github.com/kubernetes/minikube#installation[official doc] for the installation.
-
-Start a new instance of Minikube using the command:
-
-```
-minikube start
-```
-
-After the startup process is completed, you need to **enable the `registry` addon**:
-
-```
-minikube addons enable registry
-```
-
-You can now proceed to link:/README.adoc[install Camel K].
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
new file mode 100644
index 0000000..1f1f340
--- /dev/null
+++ b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,6 @@
+* xref:installation/index.adoc[Installing Camel K]
+** xref:installation/minikube.adoc[Minikube]
+** xref:installation/minishift.adoc[Minishift]
+** xref:installation/gke.adoc[Google Kubernetes Engine (GKE)]
+* xref:running.adoc[Running Integrations]
+* xref:configuration/index.adoc[Configuration]
\ No newline at end of file
diff --git a/README.adoc b/docs/modules/ROOT/pages/configuration/index.adoc
similarity index 66%
copy from README.adoc
copy to docs/modules/ROOT/pages/configuration/index.adoc
index 91790ec..2b22c19 100644
--- a/README.adoc
+++ b/docs/modules/ROOT/pages/configuration/index.adoc
@@ -1,62 +1,5 @@
-Apache Camel K
-==============
-
-image:https://travis-ci.org/apache/camel-k.svg?branch=master["Build Status", link="https://travis-ci.org/apache/camel-k"]
-image:https://goreportcard.com/badge/github.com/apache/camel-k["Go Report Card", link="https://goreportcard.com/report/github.com/apache/camel-k"]
-image:https://godoc.org/github.com/apache/camel-k?status.svg["GoDoc", link="https://godoc.org/github.com/apache/camel-k"]
-image:https://img.shields.io/github/license/openshift/origin.svg?maxAge=2592000["Licensed under Apache License version 2.0", link="https://www.apache.org/licenses/LICENSE-2.0"]
-image:https://badges.gitter.im/apache/camel-k.png["Chat on Gitter", link="https://gitter.im/apache/camel-k"]
-
-Apache Camel K (a.k.a. Kamel) is a lightweight integration framework built from Apache Camel that runs natively on Kubernetes and is specifically designed for serverless and microservice architectures.
-
-[[getting-started]]
-== Getting Started
-
-Camel K allows to run integrations directly on a Kubernetes or OpenShift cluster.
-To use it, you need to be connected to a cloud environment or to a local cluster created for development purposes.
-
-If you need help on how to create a local development environment based on *Minishift* or *Minikube*, you can follow the link:/docs/cluster-setup.adoc[local cluster setup guide].
-
-[[installation]]
-=== Installation
-
-Make sure you apply specific configuration settings for your cluster before installing Camel K. Customized instructions are needed for
-the following cluster types:
-
-- link:/docs/cluster-setup.adoc[Minishift or Minikube]
-- link:/docs/gke-setup.adoc[Google Kubernetes Engine (GKE)]
-
-Other cluster types (such as OpenShift clusters) should not need prior configuration.
-
-To start using Camel K you need the **"kamel"** binary, that can be used to both configure the cluster and run integrations.
-Look into the https://github.com/apache/camel-k/releases[release page] for latest version of the `kamel` tool.
-
-If you want to contribute, you can also **build it from source!** Refer to the link:/docs/developers.adoc[developer's guide]
-for information on how to do it.
-
-Once you have the "kamel" binary, log into your cluster using the standard "oc" (OpenShift) or "kubectl" (Kubernetes) client tool and execute the following command to install Camel K:
-
-```
-kamel install
-```
-
-This will configure the cluster with the Camel K custom resource definitions and install the operator on the current namespace.
-
-IMPORTANT: Custom Resource Definitions (CRD) are cluster-wide objects and you need admin rights to install them. Fortunately this
-operation can be done *once per cluster*. So, if the `kamel install` operation fails, you'll be asked to repeat it when logged as admin.
-For Minishift, this means executing `oc login -u system:admin` then `kamel install --cluster-setup` only for first-time installation.
-
-=== Running an Integration
-
-After the initial setup, you can run a Camel integration on the cluster by executing:
-
-```
-kamel run examples/Sample.java
-```
-
-A "Sample.java" file is included in the link:/examples[/examples] folder of this repository. You can change the content of the file and execute the command again to see the changes.
-
-==== Configure Integration properties
+[[configuration]]
+= Configure Integrations
Properties associated to an integration can be configured either using a ConfigMap/Secret or by setting using the "--property" flag, i.e.
diff --git a/docs/developers.adoc b/docs/modules/ROOT/pages/developers.adoc
similarity index 100%
rename from docs/developers.adoc
rename to docs/modules/ROOT/pages/developers.adoc
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 0000000..687600e
--- /dev/null
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,27 @@
+Apache Camel K
+==============
+
+Apache Camel K is a lightweight integration framework built from Apache Camel that runs natively on Kubernetes and is specifically designed for serverless and microservice architectures.
+
+Users of Camel K can instantly run integration code written in Camel DSL on their preferred cloud.
+
+[[how-it-works]]
+== How It Works
+
+Just write a _helloworld.groovy_ integration file with the following content:
+
+```groovy
+from('timer:tick?period=3s')
+ .setBody().constant('Hello world from Camel K')
+ .to('log:info')
+```
+
+You can then execute the following command:
+
+```
+kamel run helloworld.groovy
+```
+
+The integration code immediately runs in the cloud. **Nothing else** is needed.
+
+Continue reading the documentation to xref:installation/index.adoc[get started with Camel K].
diff --git a/docs/gke-setup.adoc b/docs/modules/ROOT/pages/installation/gke.adoc
similarity index 88%
rename from docs/gke-setup.adoc
rename to docs/modules/ROOT/pages/installation/gke.adoc
index 5bc39eb..795cdbb 100644
--- a/docs/gke-setup.adoc
+++ b/docs/modules/ROOT/pages/installation/gke.adoc
@@ -1,6 +1,5 @@
-[[gke-cluster]]
-Configuring a Google Kubernetes Engine (GKE) Cluster
-====================================================
+[[installation-on-gke]]
+= Installing Camel K on Google Kubernetes Engine (GKE)
This guide assumes you've already created a Kubernetes Engine cluster on https://console.cloud.google.com.
@@ -49,7 +48,10 @@ After the renaming, execute the following command to create the secret:
kubectl create secret generic kaniko-secret --from-file=kaniko-secret.json
```
-You're ready to install Camel K. You should now execute the following command to install cluster resources and the operator (in the current namespace):
+You're ready to install Camel K. You need to get the *kamel* CLI tool the from https://github.com/apache/camel-k/releases[release page]
+and put it on your system path.
+
+You should now execute the following command to install cluster resources and the operator (in the current namespace):
```
kamel install --registry gcr.io --organization <<your-project-id>> --push-secret kaniko-secret
diff --git a/docs/modules/ROOT/pages/installation/index.adoc b/docs/modules/ROOT/pages/installation/index.adoc
new file mode 100644
index 0000000..bc6df6b
--- /dev/null
+++ b/docs/modules/ROOT/pages/installation/index.adoc
@@ -0,0 +1,40 @@
+[[installation]]
+= Installing Camel K
+
+Camel K allows to run integrations directly on a Kubernetes or OpenShift cluster.
+To use it, you need to be connected to a cloud environment or to a local cluster created for development purposes.
+
+[[requirements]]
+== Requirements
+
+Camel K installation is usually straightforward, but for certain cluster types you need to apply specific configuration settings
+before installing it. Customized instructions are needed for the following cluster types:
+
+- xref:installation/minikube.adoc[Minikube]
+- xref:installation/minishift.adoc[Minishift]
+- xref:installation/gke.adoc[Google Kubernetes Engine (GKE)]
+
+Other cluster types (such as OpenShift clusters) should *not need* prior configuration.
+
+[[procedure]]
+== Procedure
+
+To start using Camel K you need the **"kamel"** CLI tool, that can be used to both configure the cluster and run integrations.
+Look into the https://github.com/apache/camel-k/releases[release page] for latest version of the *camel-k-client* tool for your specific platform.
+
+Download and uncompress the archive. It contains a small binary file named `kamel` that you should put into your system path.
+For example, if you're using Linux, you can put `kamel` in `/usr/bin`.
+
+Once you have put the "kamel" CLI in the path, log into your cluster using the standard "oc" (OpenShift) or "kubectl" (Kubernetes) client tool and execute the following command to install Camel K:
+
+```
+kamel install
+```
+
+This will configure the cluster with the Camel K custom resource definitions and install the operator on the current namespace.
+
+IMPORTANT: Custom Resource Definitions (CRD) are cluster-wide objects and you need admin rights to install them. Fortunately this
+operation can be done *once per cluster*. So, if the `kamel install` operation fails, you'll be asked to repeat it when logged as admin.
+For Minishift, this means executing `oc login -u system:admin` then `kamel install --cluster-setup` only for first-time installation.
+
+You're now ready to xref:running.adoc[run some integrations].
diff --git a/docs/modules/ROOT/pages/installation/minikube.adoc b/docs/modules/ROOT/pages/installation/minikube.adoc
new file mode 100644
index 0000000..5f26f2d
--- /dev/null
+++ b/docs/modules/ROOT/pages/installation/minikube.adoc
@@ -0,0 +1,19 @@
+[[installation-on-minikube]]
+= Installing Camel K on Minikube
+
+You can run Camel K integrations on plain Kubernetes using the Minikube cluster creation tool.
+Follow the instructions in the https://github.com/kubernetes/minikube#installation[official doc] for the installation.
+
+Start a new instance of Minikube using the command:
+
+```
+minikube start
+```
+
+After the startup process is completed, you need to **enable the `registry` addon**:
+
+```
+minikube addons enable registry
+```
+
+You can now proceed with the xref:installation/index.adoc#procedure[standard Camel K installation procedure].
diff --git a/docs/modules/ROOT/pages/installation/minishift.adoc b/docs/modules/ROOT/pages/installation/minishift.adoc
new file mode 100644
index 0000000..7e2564d
--- /dev/null
+++ b/docs/modules/ROOT/pages/installation/minishift.adoc
@@ -0,0 +1,21 @@
+[[installation-on-minishift]]
+= Installing Camel K on Minishift
+
+You can run Camel K integrations on OpenShift using the Minishift cluster creation tool.
+Follow the instructions in the https://github.com/minishift/minishift#getting-started[getting started guide] for the installation.
+
+After installing the `minishift` binary, you need to enable the `admin-user` addon:
+
+```
+minishift addons enable admin-user
+```
+
+NOTE: the admin user addon should be enabled before starting the cluster for the first time
+
+Then you can start the cluster with:
+
+```
+minishift start
+```
+
+You can now proceed with the xref:installation/index.adoc#procedure[standard Camel K installation procedure].
diff --git a/docs/languages.adoc b/docs/modules/ROOT/pages/languages.adoc
similarity index 100%
rename from docs/languages.adoc
rename to docs/modules/ROOT/pages/languages.adoc
diff --git a/README.adoc b/docs/modules/ROOT/pages/running.adoc
similarity index 69%
copy from README.adoc
copy to docs/modules/ROOT/pages/running.adoc
index 91790ec..d12c3f8 100644
--- a/README.adoc
+++ b/docs/modules/ROOT/pages/running.adoc
@@ -1,54 +1,12 @@
-Apache Camel K
-==============
+[[running]]
+= Running Integrations
-image:https://travis-ci.org/apache/camel-k.svg?branch=master["Build Status", link="https://travis-ci.org/apache/camel-k"]
-image:https://goreportcard.com/badge/github.com/apache/camel-k["Go Report Card", link="https://goreportcard.com/report/github.com/apache/camel-k"]
-image:https://godoc.org/github.com/apache/camel-k?status.svg["GoDoc", link="https://godoc.org/github.com/apache/camel-k"]
-image:https://img.shields.io/github/license/openshift/origin.svg?maxAge=2592000["Licensed under Apache License version 2.0", link="https://www.apache.org/licenses/LICENSE-2.0"]
-image:https://badges.gitter.im/apache/camel-k.png["Chat on Gitter", link="https://gitter.im/apache/camel-k"]
+After completing the xref:installation/index.adoc[installation] you should be connected to a Kubernetes/OpenShift cluster
+and have the "kamel" CLI correctly configured.
-Apache Camel K (a.k.a. Kamel) is a lightweight integration framework built from Apache Camel that runs natively on Kubernetes and is specifically designed for serverless and microservice architectures.
+*TODO* Continue from here!
-[[getting-started]]
-== Getting Started
-
-Camel K allows to run integrations directly on a Kubernetes or OpenShift cluster.
-To use it, you need to be connected to a cloud environment or to a local cluster created for development purposes.
-
-If you need help on how to create a local development environment based on *Minishift* or *Minikube*, you can follow the link:/docs/cluster-setup.adoc[local cluster setup guide].
-
-[[installation]]
-=== Installation
-
-Make sure you apply specific configuration settings for your cluster before installing Camel K. Customized instructions are needed for
-the following cluster types:
-
-- link:/docs/cluster-setup.adoc[Minishift or Minikube]
-- link:/docs/gke-setup.adoc[Google Kubernetes Engine (GKE)]
-
-Other cluster types (such as OpenShift clusters) should not need prior configuration.
-
-To start using Camel K you need the **"kamel"** binary, that can be used to both configure the cluster and run integrations.
-Look into the https://github.com/apache/camel-k/releases[release page] for latest version of the `kamel` tool.
-
-If you want to contribute, you can also **build it from source!** Refer to the link:/docs/developers.adoc[developer's guide]
-for information on how to do it.
-
-Once you have the "kamel" binary, log into your cluster using the standard "oc" (OpenShift) or "kubectl" (Kubernetes) client tool and execute the following command to install Camel K:
-
-```
-kamel install
-```
-
-This will configure the cluster with the Camel K custom resource definitions and install the operator on the current namespace.
-
-IMPORTANT: Custom Resource Definitions (CRD) are cluster-wide objects and you need admin rights to install them. Fortunately this
-operation can be done *once per cluster*. So, if the `kamel install` operation fails, you'll be asked to repeat it when logged as admin.
-For Minishift, this means executing `oc login -u system:admin` then `kamel install --cluster-setup` only for first-time installation.
-
-=== Running an Integration
-
-After the initial setup, you can run a Camel integration on the cluster by executing:
+You can now, you can run a Camel integration on the cluster by executing:
```
kamel run examples/Sample.java
diff --git a/docs/traits.adoc b/docs/modules/ROOT/pages/traits.adoc
similarity index 100%
rename from docs/traits.adoc
rename to docs/modules/ROOT/pages/traits.adoc