Merge pull request #7 from unbroken-dome/feature/docs

Documentation

README.adoc

@@ -10,8 +10,6 @@ endif::[]
 
 This is a suite of Gradle plugins for building, publishing and managing https://www.helm.sh/[Helm] charts.
 
-IMPORTANT: This is still work in progress!
-
 
 == Features
 
@@ -23,7 +21,7 @@ IMPORTANT: This is still work in progress!
 
 == Requirements
 
-* Gradle 4.3 or higher
+* Gradle 5.1 or higher
 * JDK 1.8 or higher (for running Gradle)
 * Helm command-line client
 
@@ -36,7 +34,7 @@ Apply the `org.unbroken-dome.helm` plugin to your Gradle project:
 [source,groovy]
 ----
 plugins {
-  id 'org.unbroken-dome.helm' version '0.2.3'
+  id 'org.unbroken-dome.helm' version '0.3.0'
 }
 ----
 
@@ -60,4 +58,5 @@ Use the `helmPackage` task to build your chart.
 
 == Further Documentation
 
-Please refer to the https://github.com/unbroken-dome/gradle-helm-plugin/wiki[Wiki] for full documentation.
+* https://unbroken-dome.github.io/projects/gradle-helm-plugin/[User Manual]
+* https://unbroken-dome.github.io/projects/gradle-helm-plugin/dokka/gradle-helm-plugin/[API/DSL Documentation]

build.gradle.kts

@@ -1,4 +1,8 @@
+import org.asciidoctor.gradle.AsciidoctorTask
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import java.net.URL
 
 
 plugins {
@@ -7,6 +11,7 @@ plugins {
     id("com.gradle.plugin-publish") version "0.10.0"
     id("org.jetbrains.dokka") version "0.9.17"
     id("maven-publish")
+    id("org.asciidoctor.convert") version "1.5.9.2"
 }
 
 
@@ -104,3 +109,35 @@ pluginBundle {
         }
     }
 }
+
+
+tasks.named("dokka", DokkaTask::class) {
+    outputFormat = "html"
+    externalDocumentationLink(delegateClosureOf<DokkaConfiguration.ExternalDocumentationLink.Builder> {
+        url = URL("https://docs.gradle.org/current/javadoc/")
+    })
+    reportUndocumented = false
+}
+
+
+asciidoctorj {
+    version = "1.6.0"
+}
+
+dependencies {
+    "asciidoctor"("com.bmuschko:asciidoctorj-tabbed-code-extension:0.2")
+}
+
+
+tasks.named("asciidoctor", AsciidoctorTask::class) {
+    sourceDir("docs")
+    sources(delegateClosureOf<PatternSet> { include("index.adoc") })
+
+    options(mapOf(
+            "doctype" to "book"
+    ))
+    attributes(mapOf(
+            "project-version" to project.version,
+            "source-highlighter" to "prettify"
+    ))
+}

docs/config-from-project-properties.adoc

@@ -0,0 +1,157 @@
+= Configuration from Project Properties
+
+Many settings can be configured by Gradle
+https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties[project properties]
+instead of specifying them in the DSL. This has the advantage that you can pass them on the command line
+(using `-P` switches) or a local `~/gradle.properties` file to account for different build environments.
+In addition, such properties are automatically inherited by subprojects.
+
+Some of these properties allow evaluation as a Groovy `GString`, so that you can do things like
+`-Phelm.home=$buildDir/helm/home` (but the dollar signs may need to be escaped so the shell does not
+treat them as environment variables).
+
+In general, the name of the project property corresponds to the path of the property in the DSL,
+e.g. `helm.home`.
+
+NOTE: Properties set explicitly in your Gradle script have precedence over properties from the command line
+or `gradle.properties` file, so it may be better to put them in `gradle.properties` in the first place, to
+allow for easier overriding.
+
+== Basic Helm Properties
+
+[cols="3,4,1"]
+|===
+| Property | Description | GString
+
+| `helm.executable`
+| Path to the Helm CLI executable. Defaults to `helm`.
+| icon:check[]
+
+| `helm.debug`
+| Enable verbose output from the Helm CLI.
+|
+
+| `helm.home`
+| Location of the Helm home directory.
+| icon:check[]
+
+| `helm.host`
+| Address of Tiller, in the format `host:port`.
+|
+
+| `helm.kubeContext`
+| Name of the kubeconfig context to use.
+|
+
+| `helm.kubeConfig`
+| Path to the Kubernetes configuration file.
+| icon:check[]
+
+| `helm.timeoutSeconds`
+| Timeout used for various Helm CLI commands.
+|
+
+| `helm.outputDir`
+| The base output directory for charts; defaults to `$buildDir/helm/charts`.
+| icon:check[]
+|===
+
+== Tiller
+
+[cols="2*"]
+|===
+| Property | Description
+
+| `helm.tiller.install`
+| If `true`, install Tiller on the cluster.
+
+| `helm.tiller.namespace`
+| Namespace of Tiller.
+
+| `helm.tiller.forceUpgrade`
+| Force upgrade of Tiller to the current Helm version.
+
+| `helm.tiller.historyMax`
+| Limit the maximum number of revisions saved per release.
+
+| `helm.tiller.replicas`
+| Amount of Tiller instances to run on the cluster.
+
+| `helm.tiller.serviceAccount`
+| Name of the service account to use for Tiller.
+
+| `helm.tiller.image`
+| Override the Tiller image.
+
+| `helm.tiller.upgrade`
+| Upgrade if Tiller is already installed.
+
+| `helm.tiller.wait`
+| Block until Tiller is running and ready to receive requests (defaults to `true`)
+
+|===
+
+== Repositories
+
+You can configure repositories entirely from Gradle properties -- just the presence of a set of
+`helm.repositories.<name>.<xyz>` properties will automatically create a corresponding repository.
+
+[cols="2*"]
+|===
+| Property | Description
+
+| `helm.repository.<name>.url`
+| The URL of the repository.
+
+| `helm.repository.<name>.credentials.username`
+| Username for password-based authentication.
+
+| `helm.repository.<name>.credentials.password`
+| Password for password-based authentication.
+
+| `helm.repository.<name>.credentials.certificateFile`
+| Client certificate file for certificate authentication.
+
+| `helm.repository.<name>.credentials.keyFile`
+| Private key file for certificate authentication.
+|===
+
+== Filtering
+
+[cols="2*"]
+|===
+| Property | Description
+
+| `helm.filtering.enabled`
+| Globally enable or disable filtering. Defaults to `true`.
+
+| `helm.filtering.placeholderPrefix`
+| Prefix that demarcates a placeholder in filtered YAML files. Defaults to `${`.
+
+| `helm.filtering.placeholderSuffix`
+| Suffix that demarcates a placeholder in filtered YAML files. Defaults to `}`.
+|===
+
+== Linting
+
+[cols="2*"]
+|===
+| Property | Description
+
+| `helm.lint.enabled`
+| Globally enable or disable linting. Defaults to `true`.
+
+| `helm.lint.strict`
+| Globally enable strict mode for linting. Defaults to `false`.
+
+|===
+
+== Releases
+
+[cols="2*"]
+|===
+| Property | Description
+
+| `helm.dryRun`
+| Only perform a dry run when installing or deleting releases.
+|===

docs/configure-helm.adoc

@@ -0,0 +1,92 @@
+= Configuring the Helm Client
+
+The global flags for Helm can be configured directly in the `helm` DSL block.
+
+Most of these correspond to options that are passed to every Helm CLI command as a parameter
+or an environment variable, or parameters that are passed to the initial `helm init` call that
+sets up the local Helm environment.
+
+[TIP]
+====
+As these settings can be dependent on the build environment, it is often useful to specify them in
+`gradle.properties` or on the command line instead.
+See <<Configuration from Project Properties>>.
+====
+
+
+The following `helm.home` sets the Helm home directory to a path inside the Gradle build directory.
+
+[source,groovy,role="primary"]
+.Groovy
+----
+helm {
+    home = file("$buildDir/helm/home")
+}
+----
+
+[source,kotlin,role="secondary"]
+.Kotlin
+----
+helm {
+    home.set(file("$buildDir/helm/home"))
+}
+----
+
+
+[TIP]
+====
+Setting the Helm home directory to a path like this is actually a good practice, as it makes your
+build less dependent on the local machine, and does not pollute the local Helm configuration.
+====
+
+The plugin splits what is usually done by `helm init` into two steps:
+
+Task `helmInitClient`::
+This will call `helm init --client-only`, skipping a remote Tiller installation. Since this sets up the
+Helm client, most other Helm tasks will have a dependency on this.
+
+Task `helmInitServer`::
+This will call `helm init` which also installs Tiller in the remote cluster. Only tasks that actually
+communicate with Tiller (like
+link:dokka/gradle-helm-plugin/org.unbrokendome.gradle.plugins.helm.command.tasks/-helm-install/[`HelmInstall`]
+or
+link:dokka/gradle-helm-plugin/org.unbrokendome.gradle.plugins.helm.command.tasks/-helm-delete/[`HelmDelete`]
+depend on this.
+
+
+== Configuring Tiller
+
+Inside the `helm.tiller` block you can configure certain settings for the remote Tiller installation.
+Most of these correspond to parameters of the `helm init` CLI command.
+
+[source,groovy,role="primary"]
+.Groovy
+----
+helm {
+    tiller {
+        // Install/expect Tiller in a different namespace than kube-system
+        namespace = "custom-namespace"
+
+        // Set a service account for Tiller
+        serviceAccount = "tiller-service-account"
+    }
+}
+----
+
+[source,kotlin,role="secondary"]
+.Kotlin
+----
+helm {
+    tiller {
+        // Install/expect Tiller in a different namespace than kube-system
+        namespace.set("custom-namespace")
+
+        // Set a service account for Tiller
+        serviceAccount.set("tiller-service-account")
+    }
+}
+----
+
+Please refer to the
+link:dokka/gradle-helm-plugin/org.unbrokendome.gradle.plugins.helm.dsl/-tiller/[API Reference] for a
+full list of configuration options.