Merge pull request #1032 from kapicorp/improve-docs-cc

Adds cookiecutter bootstap and improve documentation
kapicorp · Sep 2, 2023 · 2990f0e · 2990f0e
2 parents cf251f8 + 59146f7
commit 2990f0e
Show file tree

Hide file tree

Showing 5 changed files with 129 additions and 120 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -23,83 +23,7 @@
 
 ![demo](images/kapitan-demo.gif)
 
-## Install Kapitan
 
-[![Releases](https://img.shields.io/github/release/kapicorp/kapitan.svg)](https://github.com/kapicorp/kapitan/releases)
-
-!!! success "recommended"
-    ### Docker
-    ![Docker Pulls](https://img.shields.io/docker/pulls/kapicorp/kapitan)
-    [![Docker Image Size](https://img.shields.io/docker/image-size/kapicorp/kapitan/latest.svg)](https://hub.docker.com/r/kapicorp/kapitan)
-    [![Docker](https://github.com/kapicorp/kapitan/workflows/Docker%20Build%20and%20Push/badge.svg)](https://github.com/kapicorp/kapitan/actions?query=workflow%3A%22Docker+Build+and+Push%22)
-
-
-
-
-    === "Linux"
-
-        ```shell
-        alias kapitan="docker run -t --rm -u $(id -u) -v $(pwd):/src:delegated kapicorp/kapitan"
-        kapitan -h
-        ```
-
-    === "Mac"
-
-        ```shell
-        alias kapitan="docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan"
-        kapitan -h
-        ```
-
-### Pip 
-
-#### Install Python
-
-![Python version](https://img.shields.io/pypi/pyversions/kapitan)
-![Unit Tests](https://github.com/kapicorp/kapitan/actions/workflows/test.yml/badge.svg)
-=== "Linux"
-
-    ```shell
-    sudo apt-get update && sudo apt-get install -y python3.8-dev python3-pip python3-yaml
-    ```
-
-=== "Mac"
-
-    ```shell
-    brew install python3 libyaml libmagic
-    ```
-
-#### Install Kapitan using pip
-
-![downloads](https://img.shields.io/pypi/dm/kapitan)
-
-##### User
-
-=== "Linux"
-
-    !!! note ""
-        `kapitan` will be installed in `$HOME/.local/lib/python3.7/bin`
-
-    ```shell
-    pip3 install --user --upgrade kapitan
-    ```
-
-=== "Mac"
-
-    !!! note ""
-        `kapitan` will be installed in `$HOME/Library/Python/3.7/bin`
-
-    ```shell
-    pip3 install --user --upgrade kapitan
-    ```
-
-
-##### System-wide
-
-!!! attention "not recommended"
-
-    ```shell
-    sudo pip3 install --upgrade kapitan
-    ```
 
 ## Related projects
 

diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -1,15 +1,13 @@
 # :kapitan-logo: **Kapitan Overview**
 
-## Setup your repository
+## Setup your installation 
 
-!!! note
-    We are currently working on improving the experience to give you an even quicker experience with Kapitan
+Using our reference repositories you can easily get started with **Kapitan**
 
-### Quickstart
+### Examples repository
 
-[kapicorp/kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository is meant to be a way to bootstrap your **Kapitan** setup to get you up and running.
-
-It is meant to help you make use of best practices and libraries that can make Kapitan the ultimate tool for all your configuration needs.
+[kapicorp/kapitan-reference](https://github.com/kapicorp/kapitan-reference) repository is meant show you many working examples of things you can do with Kapitan.
+You can use this to get familiar with **Kapitan**
 
 ```
 $ git clone [email protected]:kapicorp/kapitan-reference.git kapitan-templates
@@ -30,41 +28,118 @@ Compiled pritunl (2.03s)
 Compiled sock-shop (4.36s)
 ```
 
-### From Scratch (Advanced)
-
-!!! warning
-
-    the `kapitan init` command leaves you with a bare configuration. Setting up Kapitan might require time. 
-
-    Please use the [**Quickstart**](#quickstart) setup if you want to get started quicker.
-
-If you want to start off with a clean **kapitan** project, you can run `kapitan init --directory <directory>` to populate a new directory with the recommended kapitan folder structure.
-
-The bare minimum structure that makes use of kapitan features may look as follows:
-
-```text
-.
-├── components
-│   ├── mycomponent.jsonnet
-├── templates
-├── ├── README.md
-├── inventory
-│   ├── classes
-│   │   ├── common.yml
-│   └── targets
-│       ├── dev.yml
-│       ├── staging.yml
-│       └── prod.yml
-├── refs
-│   ├── targets
-│   │   ├── prod
-│   │   │   └── password
-└───├── common
-        └── example-com-tls.key
+### Minimal repository
+
+> Using [cruft](https://cruft.github.io/cruft/) based cookiecutter
+
+```shell
+pip3 install cruft
+```
+
+```shell
+cruft create http://github.com/kapicorp/kapitan-reference --checkout cookiecutter --no-input
+Dependency https://github.com/kapicorp/generators.git: saved to system/lib
+Dependency https://github.com/kapicorp/generators.git: saved to system/generators/kubernetes
+Dependency https://github.com/kapicorp/generators.git: saved to system/generators/terraform
+Rendered inventory (1.74s)
+Compiled echo-server (0.14s)
 ```
 
-* `components`: template files for kadet, jsonnet and helm
-* `templates`: stores Jinja2 templates for scripts and documentation
-* `inventory/targets`: target files
-* `inventory/classes`: inventory classes to be inherited by targets
-* `refs`: references files
+## running **Kapitan**
+
+!!! success "recommended"
+    ### `kapitan` wrapper script
+    If you use the provided repository, we already package a `kapitan` shell script that wraps the docker command to run **Kapitan**
+
+    ```shell
+    $ ./kapitan compile
+    Compiled postgres-proxy (1.51s)
+    Compiled tesoro (1.70s)
+    Compiled echo-server (1.64s)
+    Compiled mysql (1.67s)
+    Compiled gke-pvm-killer (1.17s)
+    Compiled prod-sockshop (4.74s)
+    Compiled dev-sockshop (4.74s)
+    Compiled tutorial (1.68s)
+    Compiled global (0.76s)
+    Compiled examples (2.60s)
+    Compiled pritunl (2.03s)
+    Compiled sock-shop (4.36s)
+    ```
+
+## Other installation methods
+
+### Docker
+[![Releases](https://img.shields.io/github/release/kapicorp/kapitan.svg)](https://github.com/kapicorp/kapitan/releases)
+
+!!! success "recommended"
+    ### Docker
+    ![Docker Pulls](https://img.shields.io/docker/pulls/kapicorp/kapitan)
+    [![Docker Image Size](https://img.shields.io/docker/image-size/kapicorp/kapitan/latest.svg)](https://hub.docker.com/r/kapicorp/kapitan)
+    [![Docker](https://github.com/kapicorp/kapitan/workflows/Docker%20Build%20and%20Push/badge.svg)](https://github.com/kapicorp/kapitan/actions?query=workflow%3A%22Docker+Build+and+Push%22)
+
+
+    === "Linux"
+
+        ```shell
+        alias kapitan="docker run -t --rm -u $(id -u) -v $(pwd):/src:delegated kapicorp/kapitan"
+        kapitan -h
+        ```
+
+    === "Mac"
+
+        ```shell
+        alias kapitan="docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan"
+        kapitan -h
+        ```
+
+### Pip 
+
+#### Install Python
+
+![Python version](https://img.shields.io/pypi/pyversions/kapitan)
+![Unit Tests](https://github.com/kapicorp/kapitan/actions/workflows/test.yml/badge.svg)
+=== "Linux"
+
+    ```shell
+    sudo apt-get update && sudo apt-get install -y python3.8-dev python3-pip python3-yaml
+    ```
+
+=== "Mac"
+
+    ```shell
+    brew install python3 libyaml libmagic
+    ```
+
+#### Install Kapitan using pip
+
+![downloads](https://img.shields.io/pypi/dm/kapitan)
+
+##### User
+
+=== "Linux"
+
+    !!! note ""
+        `kapitan` will be installed in `$HOME/.local/lib/python3.7/bin`
+
+    ```shell
+    pip3 install --user --upgrade kapitan
+    ```
+
+=== "Mac"
+
+    !!! note ""
+        `kapitan` will be installed in `$HOME/Library/Python/3.7/bin`
+
+    ```shell
+    pip3 install --user --upgrade kapitan
+    ```
+
+
+##### System-wide
+
+!!! attention "not recommended"
+
+    ```shell
+    sudo pip3 install --upgrade kapitan
+    ```
diff --git a/docs/pages/blog/2023-08-27.md b/docs/pages/blog/2023-08-27.md
@@ -151,7 +151,7 @@ Here are some example "mutation" which separates different `kinds` into differen
 !!! tip "Catch-all rule"
     Notice the catchall rule at the end that puts everything that has not matched into the `bundle.yml` file
 
-### `bundle` mutation`
+### `bundle` mutation
 
 Currently most of the keda related resources are bundled into the `-bundle.yml` file
 Instead, we want to separate them into their own file.

diff --git a/docs/pages/examples/kubernetes.md b/docs/pages/examples/kubernetes.md
@@ -4,6 +4,11 @@ tags:
 ---
 # :kapitan-logo: **Kubernetes examples**
 
+!!! danger
+    This documentation is not up-to-date. 
+
+    Please refer to the [documentation](/pages/kapitan_overview/), [Getting started](/getting_started/) or look at the [Kapitan Reference](https://github.com/kapicorp/kapitan-reference) repository.
+
 Here, we walk through how kapitan could be used to help create kubernetes manifests, whose values are customized for each target according to the inventory structure. The example folder can be found in our repository on Github at <https://github.com/kapicorp/kapitan/tree/master/examples/kubernetes>.
 
 ## Directory structure

diff --git a/docs/pages/examples/terraform.md b/docs/pages/examples/terraform.md
@@ -4,6 +4,11 @@ tags:
 ---
 # :kapitan-logo: **Terraform example**
 
+!!! danger
+    This documentation is not up-to-date. 
+
+    Please refer to the [documentation](/pages/kapitan_overview/), [Getting started](/getting_started/) or look at the [Kapitan Reference](https://github.com/kapicorp/kapitan-reference) repository.
+
 We will be looking at how to use Kapitan to compile terraform files with Jsonnet as the input type. It's possible to use other input types, however, Jsonnet is recommended.
 For example, we could use the Kadet input to generate terraform files but this would require templates to be written in YAML then rendered into JSON.
 It is possible to allow Kadet to consume JSON as an input. This enables you to integrate your organizations pre-existing terraform JSON file's as templates.