docs/building.md: add docs for building Kilo and the website (#177)

* docs/building.md: add docs for building Kilo and the website

Signed-off-by: leonnicolas <leonloechner@gmx.de>

Update docs/building_kilo.md

Co-authored-by: Lucas Servén Marín <lserven@gmail.com>

* Apply suggestions from code review

Co-authored-by: Lucas Servén Marín <lserven@gmail.com>

Co-authored-by: Lucas Servén Marín <lserven@gmail.com>

docs/building_kilo.md

@@ -0,0 +1,100 @@
+# Build and Test Kilo
+
+This document describes how you can build and test Kilo.
+
+To follow along, you need to install the following utilities:
+ - `go` not for building but formatting the code and running unit tests
+ - `make`
+ - `jq`
+ - `git`
+ - `curl`
+ - `docker`
+
+## Getting Started
+
+Clone the Repository and `cd` into it.
+```shell
+git clone https://github.com/squat/kilo.git
+cd kilo
+```
+
+## Build
+
+For consistency, the Kilo binaries are compiled in a Docker container, so make sure the `docker` package is installed and the daemon is running.
+
+### Compile Binaries
+
+To compile the `kg` and `kgctl` binaries run:
+```shell
+make
+```
+Binaries are always placed in a directory corresponding to the local system's OS and architecture following the pattern `bin/<os>/<architecture>/`, so on an AMD64 machine running Linux, the binaries will be stored in `bin/linux/amd64/`.
+
+You can build the binaries for a different architecture by setting the `ARCH` environment variable before invoking `make`, e.g.:
+```shell
+ARCH=<arm|arm64|amd64> make
+```
+
+Likewise, to build `kg` for another OS, set the `OS` environment variable before invoking `make`:
+```shell
+OS=<windows|darwin|linux> make
+```
+## Test
+
+To execute the unit tests, run:
+```shell
+make unit
+```
+
+To lint the code in the repository, run:
+```shell
+make lint
+```
+
+To execute basic end to end tests, run:
+```shell
+make e2e
+```
+__Note__: The end to end tests are currently flaky, so try running them again if they fail.
+
+To instead run all of the tests with a single command, run:
+```shell
+make test
+```
+
+## Build and Push the Container Images
+
+If you want to build containers for a processor architecture that is different from your computer's, then you will first need to configure QEMU as the interpreter for binaries built for non-native architectures:
+```shell
+docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
+```
+
+Set the `$IMAGE` environment variable to `<your Docker Hub user name>/kilo`.
+This way the generated container images and manifests will be named accordingly.
+By skipping this step, you will be able to tag images but will not be able to push the containers and manifests to your own Docker Hub.
+```shell
+export IMAGE=<docker hub user name>/kilo
+```
+
+If you want to use a different container registry, run:
+```shell
+export REGISTRY=<your registry without a trailing slash>
+```
+
+To build containers with the `kg` image for `arm`, `arm64` and `amd64`, run:
+```shell
+make all-container
+```
+
+Push the container images and build a manifest with:
+```shell
+make manifest
+```
+
+To tag and push the manifest with `latest`, run:
+```shell
+make manifest-latest
+```
+
+Now you can deploy the custom build of Kilo to your cluster.
+If you are already running Kilo, change the image from `squat/kilo` to `[registry/]<username>/kilo[:sha]`.

docs/building_website.md

@@ -0,0 +1,44 @@
+# Build and Test the Website
+
+You may have noticed that the `markdown` files in the `/docs` directory are also displayed on [Kilo's website](https://kilo.squat.ai/).
+If you want to add documentation to Kilo, you can start a local webserver to check out how the website would look like.
+
+## Requirements
+
+Install [yarn](https://yarnpkg.com/getting-started/install).
+
+## Build and Run
+
+The markdown files for the website are located in `/website/docs` and are generated from the like-named markdown files in the `/docs` directory and from the corresponding header files without the `.md` extension in the `/website/docs` directory.
+To generate the markdown files in `/website/docs`, run:
+```shell
+make website/docs/README.md
+```
+
+Next, build the website itself by installing the `node_modules` and building the website's HTML from the generated markdown:
+```shell
+make website/build/index.html
+```
+
+Now, start the website server with:
+```shell
+yarn --cwd website start
+```
+This command should have opened a browser window with the website; if not, open your browser and point it to `http://localhost:3000`.
+
+If you make changes to any of the markdown files in `/docs` and want to reload the local `node` server, run:
+```shell
+make website/docs/README.md -B
+```
+
+You can execute the above while the node server is running and the website will be rebuilt and reloaded automatically.
+
+## Add a New File to the Docs
+
+If you add a new file to the `/docs` directory, you also need to create a corresponding header file containing the front-matter in `/website/docs/`.
+Then, regenerate the markdown for the website with the command:
+```shell
+make website/docs/README.md
+```
+Edit `/website/sidebars.js` accordingly.
+_Note:_ The `id` in the header file `/website/docs/<new file>` must match the `id` specified in `website/sidebars.js`.

website/docs/building_kilo

@@ -0,0 +1,5 @@
+---
+id: building_kilo
+title: Building Kilo
+hide_title: true
+---

website/docs/building_website

@@ -0,0 +1,5 @@
+---
+id: building_website
+title: Building the Website
+hide_title: true
+---

website/sidebars.js

@@ -14,6 +14,11 @@ module.exports = {
       label: 'Reference',
       items: ['annotations', 'kg', 'kgctl', 'api'],
     },
+    {
+      type: 'category',
+      label: 'Contributing',
+      items: ['building_kilo', 'building_website'],
+    },
     //Features: ['mdx'],
   ],
 };