Restructure App Developer Guide

Use the structure described in RFC # and add some tests

Signed-off-by: Aidan Delaney <[email protected]>

content/docs/app-developer-guide/_index.md

@@ -1,6 +1,6 @@
 +++
-title="App Developer Guide"
-weight=4
+title="For App Developers"
+weight=1
 include_summaries=true
 expand=true
 +++

content/docs/app-developer-guide/build-an-app.md

@@ -10,8 +10,32 @@ aliases=[
 # Build an app
 `+-->
 
+<!-- test:suite=create-app;weight=1 -->
+
+<!-- test:setup:exec;exit-code=-1 -->
+<!--
+```bash
+docker rmi sample-app
+pack config trusted-builders add cnbs/sample-builder:jammy
+```
+-->
+
+<!-- test:teardown:exec -->
+<!--
+```bash
+docker rmi sample-app
+```
+-->
+
 Building an app using Cloud Native Buildpacks is as easy as `1`, `2`, `3`...
 
+## Prerequisites
+
+A lot of the examples used within this guide will require the following: 
+
+{{< 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 {{</>}}
+
 ### 1. Select a builder
 
 To [build][build] an app you must first decide which [builder][builder] you're going to use. A builder
@@ -28,18 +52,22 @@ pack builder suggest
 For this guide we're actually going to use a sample builder, `cnbs/sample-builder:jammy`, which is not listed
 as a suggested builder for good reason. It's a sample.
 
+> **TIP:**  If you want to try production grade buildpacks, instead of our sample, use the `paketobuildpacks/builder:full` builder.  Alternatively, if you intend to deploy your application on Google Cloud Run, use try the `Google` builder.  If your intended platform is Heroku, use the `Heroku` builder.
+
 ### 2. Build your app
 
 Now that you've decided on what builder to use, we can build our app. For this example we'll use our [samples][samples]
 repo for simplicity.
 
 1. Check that the samples repo exists and if not - we clone it
+<!-- test:exec -->
 ```
 ls samples || git clone https://github.com/buildpacks/samples
 ```
 <!--+- "{{execute}}"+-->
 
 2. Build the app
+<!-- test:exec -->
 ```
 pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-builder:jammy
 ```
@@ -51,8 +79,11 @@ pack build sample-app --path samples/apps/java-maven --builder cnbs/sample-build
 
 ### 3. Run it
 
+Here we `--name` the running container so that we can clean up after it:
+
+<!-- test:exec -->
 ```
-docker run --rm -p 8080:8080 sample-app
+docker run --rm -p 8080:8080 --name sample-app sample-app
 ```
 <!--+- "{{execute}}"+-->
 
@@ -62,18 +93,36 @@ docker run --rm -p 8080:8080 sample-app
 The app should now be running and accessible via [localhost:8080](http://localhost:8080).
 <!--+end+-->
 
-<!--+ `
 Now open your favorite browser and point it to port "8080" of your host 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)
-` +-->
+### 4. Verify it
+
+Executing
+
+<!-- test:exec -->
+```
+curl http://localhost:8080
+```
+
+should contain the `<title>`
+<!-- test:assert=contains -->
+```text
+Buildpacks.io Java Sample
+```
+
+### 5. Clean it up
+
+<!-- test:exec -->
+```
+docker kill sample-app
+```
 
 ## What about ARM apps?
 
 Linux ARM image builds are now supported!
 
 <!--+- if false+-->
-<a href="/docs/app-developer-guide/build-an-arm-app" class="button bg-blue">Linux ARM build guide</a>
+<a href="/docs/app-developer-guide/how-to/build-an-arm-app" class="button bg-blue">Linux ARM build guide</a>
 <!--+end+-->
 
 <!--+ `
@@ -84,7 +133,7 @@ Check out the [Linux ARM build guide](https://buildpacks.io//docs/app-developer-
 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>
+<a href="/docs/app-developer-guide/how-to/build-a-windows-app" class="button bg-blue">Windows build guide</a>
 <!--+end+-->
 <!--+ `
 Check out the [Windows build guide](https://buildpacks.io/docs/app-developer-guide/build-a-windows-app/).

content/docs/concepts/_index.md → content/docs/app-developer-guide/concepts/_index.md

@@ -1,6 +1,6 @@
 +++
 title="Concepts"
-weight=3
+weight=1000
 expand=false
 +++
 

content/docs/app-developer-guide/how-to/_index.md

@@ -0,0 +1,5 @@
++++
+title="How To"
+weight=100
+summary="Short focused guides to performing a specific task"
++++

content/docs/app-developer-guide/building-on-podman.md → content/docs/app-developer-guide/how-to/building-on-podman.md

@@ -1,6 +1,6 @@
 +++
-title="Building on Podman"
-weight=99
+title="(Advanced) Building on Podman"
+weight=20
 summary="Use podman as an alternative to Docker with Cloud Native Buildpacks."
 aliases=[
     "/docs/using-pack/building-app/"

content/docs/app-developer-guide/environment-variables.md → content/docs/app-developer-guide/how-to/using-environment-variables.md

@@ -1,6 +1,6 @@
 +++
 title="Environment variables"
-weight=3
+weight=2
 summary="Environment variables are a common way to configure various buildpacks at build-time."
 +++
 <!--+- `

content/docs/app-developer-guide/tutorials/_index.md

@@ -0,0 +1,5 @@
++++
+title="Tutorials"
+weight=200
+summary="Introductory articles that describe details"
++++

content/docs/app-developer-guide/build-a-windows-app.md → content/docs/app-developer-guide/tutorials/build-a-windows-app.md

@@ -1,6 +1,6 @@
 +++
-title="Build a Windows app"
-weight=2
+title="(Advanced) Build a Windows app"
+weight=20
 summary="The basics of taking your Windows app from source code to runnable image."
 +++
 

content/docs/app-developer-guide/build-an-arm-app.md → content/docs/app-developer-guide/tutorials/build-an-arm-app.md

@@ -1,6 +1,6 @@
 +++
-title="Build an ARM app"
-weight=2
+title="(Advanced) Build an ARM app"
+weight=20
 summary="The basics of taking your app from source code to runnable ARM image."
 +++
 

content/docs/buildpack-author-guide/_index.md

@@ -1,5 +1,5 @@
 +++
-title="Buildpack Author Guide"
+title="For Buildpack Authors"
 weight=4
 include_summaries=true
 expand=true

content/docs/platform-guide/_index.md

@@ -1,6 +1,6 @@
 +++
-title="Platform Guide"
-weight=6
+title="For Platform Operators"
+weight=3
 include_summaries=true
 expand=true
 +++