Generate adoc copies in /content/en/docs to shipwright-io#78

config.toml

@@ -82,13 +82,13 @@ copyright = "The Shipwright Contributors"
 # This menu appears only if you have at least one [params.versions] set.
 version_menu = "Releases"
 
-# Flag used in the "version-banner" partial to decide whether to display a 
+# Flag used in the "version-banner" partial to decide whether to display a
 # banner on every page indicating that this is an archived version of the docs.
 # Set this flag to "true" if you want to display the banner.
 archived_version = false
 
 # The version number for the version of the docs represented in this doc set.
-# Used in the "version-banner" partial to display a version number for the 
+# Used in the "version-banner" partial to display a version number for the
 # current doc set.
 version = "0.0"
 
@@ -137,7 +137,7 @@ yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/i
 no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
 
 # Adds a reading time to the top of each doc.
-# If you want this feature, but occasionally need to remove the Reading time from a single page, 
+# If you want this feature, but occasionally need to remove the Reading time from a single page,
 # add "hide_readingtime: true" to the page's front matter
 [params.ui.readingtime]
 enable = false
@@ -186,3 +186,17 @@ enable = false
   [security.http]
     methods = ['(?i)GET|POST']
     urls = ['.*']
+
+[markup]
+  [markup.asciidocExt]
+    backend = 'html5'
+    extensions = []
+    failureLevel = 'fatal'
+    noHeaderOrFooter = true
+    preserveTOC = false
+    safeMode = 'unsafe'
+    sectionNumbers = false
+    trace = false
+    verbose = false
+    workingFolderCurrent = false
+    [markup.asciidocExt.attributes]

content/en/_index.adoc

@@ -0,0 +1,135 @@
+= Documentation
+:draft: false
+:linkTitle: Documentation
+:menu: {"main"=>{"weight"=>20}}
+:no_list: true
+:weight: 20
+
+Shipwright is an extensible framework for building container images on Kubernetes.
+
+Shipwright supports popular tools such as Kaniko, Cloud Native Buildpacks, Buildah, and more!
+
+Shipwright is based around four elements for each build:
+
+. Source code - the "what" you are trying to build
+. Output image - "where" you are trying to deliver your application
+. Build strategy - "how" your application is assembled
+. Invocation - "when" you want to build your application
+
+== Comparison with local image builds
+
+Developers who use Docker are familiar with this process:
+
+. Clone source from a git-based repository ("what")
+. Build the container image ("when" and "how")
+
+[,bash]
+----
+  docker build -t registry.mycompany.com/myorg/myapp:latest .
+----
+
+. Push the container image to your registry ("where")
+
+[,bash]
+----
+  docker push registry.mycompany.com/myorg/myapp:latest
+----
+
+== Shipwright Build APIs
+
+Shipwright's Build API consists of four core
+https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions[CustomResourceDefinitions]
+(CRDs):
+
+. link:/docs/api/build/[`Build`] - defines what to build, and where the application should be delivered.
+. link:/docs/api/buildstrategies/[`BuildStrategy` and `ClusterBuildStrategy`] - defines how to build an application for an image
+building tool.
+. link:/docs/api/buildrun/[`BuildRun`] - invokes the build. +
+You create a `BuildRun` to tell Shipwright to start building your application.
+
+=== Build
+
+The `Build` object provides a playbook on how to assemble your specific application. The simplest
+build consists of a git source, a build strategy, and an output image:
+
+[,yaml]
+----
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: kaniko-golang-build
+  annotations:
+    build.build.dev/build-run-deletion: "true"
+spec:
+  source:
+    url: https://github.com/sbose78/taxi
+  strategy:
+    name: kaniko
+    kind: ClusterBuildStrategy
+  output:
+    image: registry.mycompany.com/my-org/taxi-app:latest
+----
+
+Builds can be extended to push to private registries, use a different Dockerfile, and more.
+
+=== BuildStrategy and ClusterBuildStrategy
+
+`BuildStrategy` and `ClusterBuildStrategy` are related APIs to define how a given tool should be
+used to assemble an application. They are distinguished by their scope - `BuildStrategy` objects
+are namespace scoped, whereas `ClusterBuildStrategy` objects are cluster scoped.
+
+The spec of a `BuildStrategy` or `ClusterBuildStrategy` consists of a `buildSteps` object, which look and feel like Kubernetes container
+specifications. Below is an example spec for Kaniko, which can build an image from a
+Dockerfile within a container:
+
+[,yaml]
+----
+# this is a fragment of a manifest
+spec:
+  buildSteps:
+    - name: build-and-push
+      image: gcr.io/kaniko-project/executor:v1.3.0
+      workingDir: /workspace/source
+      securityContext:
+        runAsUser: 0
+        capabilities:
+          add:
+            - CHOWN
+            - DAC_OVERRIDE
+            - FOWNER
+            - SETGID
+            - SETUID
+            - SETFCAP
+      env:
+        - name: DOCKER_CONFIG
+          value: /tekton/home/.docker
+      command:
+        - /kaniko/executor
+      args:
+        - --skip-tls-verify=true
+        - --dockerfile=$(build.dockerfile)
+        - --context=/workspace/source/$(build.source.contextDir)
+        - --destination=$(build.output.image)
+        - --oci-layout-path=/workspace/output/image
+        - --snapshotMode=redo
+      resources:
+        limits:
+          cpu: 500m
+          memory: 1Gi
+        requests:
+          cpu: 250m
+          memory: 65Mi
+----
+
+=== BuildRun
+
+Each `BuildRun` object invokes a build on your cluster. You can think of these as a Kubernetes
+`Jobs` or Tekton `TaskRuns` - they represent a workload on your cluster, ultimately resulting in a
+running `Pod`. See link:/docs/buildrun/[`BuildRun`] for more details.
+
+== Further reading
+
+* link:/docs/configuration/[Configuration]
+* Build controller observability
+ ** link:/docs/metrics/[Metrics]
+ ** link:/docs/profiling/[Profiling]

content/en/docs/_index.adoc

@@ -0,0 +1,135 @@
+= Documentation
+:draft: false
+:linkTitle: Documentation
+:menu: {"main"=>{"weight"=>20}}
+:no_list: true
+:weight: 20
+
+Shipwright is an extensible framework for building container images on Kubernetes.
+
+Shipwright supports popular tools such as Kaniko, Cloud Native Buildpacks, Buildah, and more!
+
+Shipwright is based around four elements for each build:
+
+. Source code - the "what" you are trying to build
+. Output image - "where" you are trying to deliver your application
+. Build strategy - "how" your application is assembled
+. Invocation - "when" you want to build your application
+
+== Comparison with local image builds
+
+Developers who use Docker are familiar with this process:
+
+. Clone source from a git-based repository ("what")
+. Build the container image ("when" and "how")
+
+[,bash]
+----
+  docker build -t registry.mycompany.com/myorg/myapp:latest .
+----
+
+. Push the container image to your registry ("where")
+
+[,bash]
+----
+  docker push registry.mycompany.com/myorg/myapp:latest
+----
+
+== Shipwright Build APIs
+
+Shipwright's Build API consists of four core
+https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions[CustomResourceDefinitions]
+(CRDs):
+
+. link:/docs/api/build/[`Build`] - defines what to build, and where the application should be delivered.
+. link:/docs/api/buildstrategies/[`BuildStrategy` and `ClusterBuildStrategy`] - defines how to build an application for an image
+building tool.
+. link:/docs/api/buildrun/[`BuildRun`] - invokes the build. +
+You create a `BuildRun` to tell Shipwright to start building your application.
+
+=== Build
+
+The `Build` object provides a playbook on how to assemble your specific application. The simplest
+build consists of a git source, a build strategy, and an output image:
+
+[,yaml]
+----
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: kaniko-golang-build
+  annotations:
+    build.build.dev/build-run-deletion: "true"
+spec:
+  source:
+    url: https://github.com/sbose78/taxi
+  strategy:
+    name: kaniko
+    kind: ClusterBuildStrategy
+  output:
+    image: registry.mycompany.com/my-org/taxi-app:latest
+----
+
+Builds can be extended to push to private registries, use a different Dockerfile, and more.
+
+=== BuildStrategy and ClusterBuildStrategy
+
+`BuildStrategy` and `ClusterBuildStrategy` are related APIs to define how a given tool should be
+used to assemble an application. They are distinguished by their scope - `BuildStrategy` objects
+are namespace scoped, whereas `ClusterBuildStrategy` objects are cluster scoped.
+
+The spec of a `BuildStrategy` or `ClusterBuildStrategy` consists of a `buildSteps` object, which look and feel like Kubernetes container
+specifications. Below is an example spec for Kaniko, which can build an image from a
+Dockerfile within a container:
+
+[,yaml]
+----
+# this is a fragment of a manifest
+spec:
+  buildSteps:
+    - name: build-and-push
+      image: gcr.io/kaniko-project/executor:v1.3.0
+      workingDir: /workspace/source
+      securityContext:
+        runAsUser: 0
+        capabilities:
+          add:
+            - CHOWN
+            - DAC_OVERRIDE
+            - FOWNER
+            - SETGID
+            - SETUID
+            - SETFCAP
+      env:
+        - name: DOCKER_CONFIG
+          value: /tekton/home/.docker
+      command:
+        - /kaniko/executor
+      args:
+        - --skip-tls-verify=true
+        - --dockerfile=$(build.dockerfile)
+        - --context=/workspace/source/$(build.source.contextDir)
+        - --destination=$(build.output.image)
+        - --oci-layout-path=/workspace/output/image
+        - --snapshotMode=redo
+      resources:
+        limits:
+          cpu: 500m
+          memory: 1Gi
+        requests:
+          cpu: 250m
+          memory: 65Mi
+----
+
+=== BuildRun
+
+Each `BuildRun` object invokes a build on your cluster. You can think of these as a Kubernetes
+`Jobs` or Tekton `TaskRuns` - they represent a workload on your cluster, ultimately resulting in a
+running `Pod`. See link:/docs/buildrun/[`BuildRun`] for more details.
+
+== Further reading
+
+* link:/docs/configuration/[Configuration]
+* Build controller observability
+ ** link:/docs/metrics/[Metrics]
+ ** link:/docs/profiling/[Profiling]