Auto-generate katacoda docs

Signed-off-by: Sambhav Kothari <[email protected]>

Author: sambhav

.github/workflows/main.yml

@@ -34,6 +34,9 @@ jobs:
       - name: Check links
         run: |
           make check-links
+      - name: Check katacoda
+        run: |
+          make check-katacoda
       - name: Upload public folder
         uses: actions/[email protected]
         env:

Makefile

@@ -157,4 +157,17 @@ prepare-for-pr: check-links test tools-tidy
 	@echo "========"
 	@echo "It looks good! :)"
 	@echo "Make sure to commit all changes!"
-	@echo "========"
+	@echo "========"
+
+.PHONY: katacoda
+katacoda:
+	@echo "========"
+	@echo "Generating Katacoda docs..."
+	@go run katacoda/main.go
+	@echo "All done!"
+	@echo "========"
+
+.PHONY: check-katacoda
+check-katacoda: katacoda
+	@echo "Checking if Katacoda docs are up-to-date..."
+	@git diff --quiet HEAD -- katacoda/scenarios || ( echo "Katacoda docs are not up-to-date! Please run 'make katacoda' and commit the katacoda/scenarios folder" && exit 1)

content/docs/app-journey.md

@@ -7,15 +7,15 @@ getting-started=true
 ## Pack for the journey
 
 In this tutorial, we'll explain how to use `pack` and **buildpacks** to create a runnable app image from source code.
-
+<!--+if false+-->
 {{< katacoda-button href="https://katacoda.com/buildpacks/scenarios/app-journey" color="green" >}} Learn on Katacoda {{</>}}
 
 In order to run the build process in an isolated fashion, `pack` uses **Docker**. That means you'll need to make sure you have both `docker` and `pack` installed:
 
 {{< download-button href="https://store.docker.com/search?type=edition&offering=community" color="blue" >}} Install Docker {{</>}}
 
 {{< download-button href="/docs/install-pack" color="pink" >}} Install pack {{</>}}
-
+<!--+end+-->
 > **NOTE:** `pack` is only one implementation of the [Cloud Native Buildpacks Platform Specification][cnb-platform-spec]. Additionally, not all Cloud Native Buildpacks Platforms require Docker.
 
 [cnb-platform-spec]: https://github.com/buildpacks/spec/blob/main/platform.md
@@ -42,24 +42,32 @@ instance, an **NPM buildpack** might look for a `package.json`, and a **Go build
 
 ### What is a [builder][builder]?
 
-{{< summary "/docs/concepts/components/builder" >}}
+A builder is an image that contains all the components necessary to execute a build. A builder image is created by taking a build image and adding a lifecycle, buildpacks, and files that configure aspects of the build including the buildpack detection order and the location(s) of the run image.
 
 ## Next stop, the end
 
 Let's see all this in action using `pack build`.
 
 Run the following commands in a shell to clone and build this [simple Java app][samples-java-maven].
 
-```bash
-# clone the repo
+1. Clone the samples repo.
+```
 git clone https://github.com/buildpacks/samples
+``` 
+<!--+- "{{execute}}"+-->
 
-# go to the app directory
+2. Go to the Java apps sub-directory
+```
 cd samples/apps/java-maven
+```
+<!--+- "{{execute}}"+-->
 
-# build the app
+3. Build the app using [`pack`][pack-docs]
+```
 pack build myapp --builder cnbs/sample-builder:bionic
 ```
+<!--+- "{{execute}}"+-->
+
 
 > **NOTE:** This is your first time running `pack build` for `myapp`, so you'll notice that
 > **the build might take longer than usual.** Subsequent builds will take advantage of various forms of caching.
@@ -77,8 +85,15 @@ To test out your new app image locally, you can run it with Docker:
 ```bash
 docker run --rm -p 8080:8080 myapp
 ```
-
+<!--+- "{{execute}}"+-->
+<!--+- if false+-->
 Now hit [`localhost:8080`](http://localhost:8080) in your favorite browser and take a minute to enjoy the view.
+<!--+- end+-->
+<!--+ `
+Now hit open the port "8080" of your host in your favorite browser and take a minute to enjoy the view.
+
+On Katacoda you can do this by [clicking here](https://[[HOST_SUBDOMAIN]]-8080-[[KATACODA_HOST]].environments.katacoda.com)
+` +-->
 
 ### Take your image to the skies
 
@@ -92,9 +107,17 @@ deploying your new image to your favorite cloud!
 
 Windows image builds are now supported!
 
+<!--+- if false+-->
 <a href="/docs/app-developer-guide/build-a-windows-app" class="button bg-blue">Windows build guide</a>
 
 [builder]: /docs/concepts/components/builder/
 [buildpack]: /docs/concepts/components/buildpack/
 [samples-java-maven]: https://github.com/buildpacks/samples/tree/main/apps/java-maven
 [pack-docs]: /docs/tools/pack/
+<!--+end+-->
+
+<!--+ `[builder]: https://buildpacks.io/docs/concepts/components/builder/
+[buildpack]: https://buildpacks.io/docs/concepts/components/buildpack/
+[samples-java-maven]: https://buildpacks.iohttps://github.com/buildpacks/samples/tree/main/apps/java-maven
+[pack-docs]: https://buildpacks.io/docs/tools/pack/
+` +-->

katacoda.yaml

@@ -0,0 +1 @@
+scenario_root : katacoda/scenarios

katacoda/files.txt

@@ -0,0 +1 @@
+content/docs/app-journey.md,katacoda/scenarios/app-journey/step1.md

katacoda/main.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"encoding/csv"
+	"log"
+	"os"
+	"regexp"
+	"strings"
+	"text/template"
+)
+
+func getMappings() ([][]string, error) {
+	file, err := os.Open("katacoda/files.txt")
+	defer file.Close()
+	if err != nil {
+		return nil, err
+	}
+	return csv.NewReader(file).ReadAll()
+}
+
+func main() {
+	files, err := getMappings()
+	if err != nil {
+		log.Fatalf("unable to read input files: %w", err)
+	}
+	frontMatter := regexp.MustCompile(`(?s)\+\+\+.*\+\+\+`)
+	for _, mapping := range files {
+		i := mapping[0]
+		o := mapping[1]
+		out, err := os.ReadFile(i)
+		out = frontMatter.ReplaceAll(out, []byte(""))
+		if err != nil {
+			log.Fatalf("unable to read input file %s: %s", i, err)
+		}
+		t, err := template.New("example").Delims("<!--+", "+-->").Parse(strings.TrimSpace(string(out)))
+		if err != nil {
+			log.Fatalf("unable to parse file %s: %s", i, err)
+		}
+		f, err := os.Create(o)
+		if err != nil {
+			log.Fatalf("create file: ", err)
+		}
+		if err := t.Execute(f, []string{}); err != nil {
+			log.Fatalf("unable to execute template: %s", err)
+		}
+	}
+}

katacoda/scenarios/app-journey/background.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+(curl -sSL "https://github.com/buildpacks/pack/releases/download/v0.18.1/pack-v0.18.1-linux.tgz" | sudo tar -C /usr/local/bin/ --no-same-owner -xzv pack)
+docker pull cnbs/sample-builder:bionic
+docker pull buildpacksio/lifecycle

katacoda/scenarios/app-journey/finish.md

@@ -0,0 +1,17 @@
+## All done
+
+Congratulations! You have successfully created your first app using buildpacks!
+
+### Take your image to the skies
+
+`pack` uses **buildpacks** to help you easily create OCI images that you can run just about anywhere. Try
+deploying your new image to your favorite cloud!
+
+> In case you need it, `pack build` has a handy flag called `--publish` that will build your image directly onto a Docker
+> registry. You can learn more about `pack` features in the [documentation][pack-docs].
+
+
+[builder]: https://buildpacks.io/docs/concepts/components/builder/
+[buildpack]: https://buildpacks.io/docs/concepts/components/buildpack/
+[samples-java-maven]: https://github.com/buildpacks/samples/tree/main/apps/java-maven
+[pack-docs]: https://buildpacks.io/docs/tools/pack/

katacoda/scenarios/app-journey/foreground.sh

@@ -0,0 +1 @@
+echo "Waiting for environment to be set up"; while [ ! -f /usr/local/bin/pack ] ; do sleep 1; done; echo "Done"

katacoda/scenarios/app-journey/index.json

@@ -0,0 +1,28 @@
+{
+  "title": "An App’s Brief Journey from Source to Image",
+  "description": "Create an application container image using Cloud Native Buildpacks",
+  "difficulty": "Beginner",
+  "time": "10",
+  "details": {
+    "steps": [
+      {
+        "title": "Step 1",
+        "text": "step1.md"
+      }
+    ],
+    "intro": {
+      "courseData": "background.sh",
+      "code": "foreground.sh",
+      "text": "intro.md"
+    },
+    "finish": {
+      "text": "finish.md"
+    }
+  },
+  "environment": {
+    "uilayout": "terminal"
+  },
+  "backend": {
+    "imageid": "ubuntu:2004"
+  }
+}