docs: restructure the README and docs folder

Author: JGiola

README.md

@@ -1,73 +1,68 @@
 # vab
 
+<center>
+
+[![Build Status][github-actions-svg]][github-actions]
+[![Go Report Card][go-report-card]][go-report-card-link]
+[![GoDoc][godoc-svg]][godoc-link]
+
+</center>
+
 `vab` is a cli for managing the installation of day 2 operation tools on multiple kubernetes clusters for easier
 management and updates.
 
 `vab` is the acronym for Vehicle Assembly Building that is designed to assemble large pre-manufactured
 space vehicle components.
 
-## Building
+## To Start Using `vab`
+
+Read the documentation [here](./docs/10_overview.md).
+
+## To Start Developing `vab`
 
-`vab` provides various make command to handle various tasks that you may need during development, but you need at
-least these dependencies installed on your machine:
+To start developing the CLI you must have this requirements:
 
+- golang 1.22
 - make
-- bash
-- docker with buildkit build engine available to use
-- golang, for the exact version see the [.go-version](/.go-version) file in the repository
 
-Once you have all the correct dependencies installed and the code pulled you can build the project with:
+Once you have pulled the code locally, you can build the code with make:
 
-```bash
+```sh
 make build
 ```
 
-This command will build the cli for your actual OS and architecture and will put the binary inside the folder
-`bin/<os>/<arch>/`.
+`make` will download all the dependencies needed and will build the binary for your current system that you can find
+in the `bin` folder.
 
-Or run the tests with:
+To build the docker image locally run:
 
-```bash
-make test
+```sh
+make docker-build
 ```
 
-If you don’t plan to build a docker image but only to contribute to the code, we provide a devcontainer configuration
-that will setup the correct dependencies and predownload the tools used for linting. Also if you use VSCode it will
-setup three extensions that we recommend.
+## Testing `vab`
 
-### Linting
+To run the tests use the command:
 
-For linting your files make provide the following command:
-
-```bash
-make lint
+```sh
+make test
 ```
 
-This command will run `go mod tidy` for cleaning up the `go.mod` and `go.sum` files.  
-Additionally the command will download and use the [`golangci-lint`][golangci-lint] cli for running various linters
-on the code, the configuration used can be seen [here](.golangci.yml).
-
-### Building Docker Image
+Or add the `DEBUG_TEST` flag to run the test with debug mode enabled:
 
-If you need to use a docker image locally you can build it with:
-
-```bash
-make docker-build
+```sh
+make test DEBUG_TEST=1
 ```
 
-The command will first build the appropriate binary and then build the correct docker image for
-your platform based on Linux Alpine.
+Before sending a PR be sure that all the linter pass with success:
 
-### Building Multiarch Docker Image
-
-If you need to try and build a multiarch docker image locally, you have to run these commands:
-
-```bash
-make docker-setup-multiarch
-make docker-build-multiarch
+```sh
+make lint
 ```
 
-For building this image you need to have installed `docker` and the `buildx` extension for emulating multiple
-architecture on your pc. This command for now is created for using it in the ci.
-
-[golangci-lint]: https://golangci-lint.run (Fast linters Runner for Go)
+[github-actions]: https://github.com/mia-platform/vab/actions
+[github-actions-svg]: https://github.com/mia-platform/vab/workflows/Continuous%20Integration%20Pipeline/badge.svg
+[godoc-svg]: https://godoc.org/github.com/mia-platform/vab?status.svg
+[godoc-link]: https://godoc.org/github.com/mia-platform/vab
+[go-report-card]: https://goreportcard.com/badge/github.com/mia-platform/vab
+[go-report-card-link]: https://goreportcard.com/report/github.com/mia-platform/vab

docs/10_overview.md

@@ -0,0 +1,42 @@
+# vab CLI
+
+`vab` is a Command Line Interface that simplify the management of the Magellano kubernetes distribution on one or
+more remote clusters.
+
+In future it will also allow to download custom modules and addons that follow the design documentations.
+
+In essence vab can be viewed as an utility for downloading and setting up [kustomization] files with a structure
+that allow sharing adding and patching resources that will be applied on different Kubernetes clusters.  
+The structure that is created and mantained by the tools can alse be used with different tools that support `kustomize`
+files like [Argo CD].
+
+Applying the configuration files with `vab` will bring additional capabilities than using `kustomize` directly like
+finer resource ordering, applied resoruce tracking for pruning resources not available in subsequent apply,
+a little bit of validation for missing resource types in the target cluster and chaining deployments against
+multiple cluster grouped together with a single command.
+
+## Functionalities
+
+The `vab` CLI functionalities can be summarized within its main subcommands:
+
+- `apply`: apply all the manifests to one or more targeted cluster specified in the configuration file
+- `build`: print all the manifests that the `apply` command would eventually apply to the cluster(s)
+- `create`: create and empty configuration file and starting files structures in the target folder
+- `sync`: donwload the modules and addons of the distribution locally and update the file structure if needed
+- `validate`: validate the configuration file to check its validity or attention points
+
+## Guides
+
+Below, you can find additional documentaion for `vab`:
+
+- [Setup](./20_setup.md)
+- [Configuration Grammar](./30_grammar.md)
+- Design Documentation
+  - [Configuration](./design/10_configuration.md)
+  - [Folder Structures](./design/20_folder-structure.md)
+  - [Modules](./design/30_modules.md)
+  - [Addons](./design/40_addons.md)
+  - [Download Packages](./design/50_download-packages.md)
+
+[kustomization]: https://kustomize.io "Kubernetes native configuration management"
+[Argo CD]: https://argo-cd.readthedocs.io/en/stable/ "Declarative GitOps CD for Kubernetes"

docs/20_setup.md

@@ -0,0 +1,154 @@
+# Setup
+
+## Installation
+
+`vab` can be installed in different ways, you can choose the one that better fits your needs and the operating system
+you are using:
+
+- [Linux and MacOs](#linux-and-macos)
+  - [Homebrew](#homebrew)
+  - [Go](#go)
+  - [Binary Download](#binary-download)
+  - [Docker](#docker)
+- [Windows (with WSL)](#windows)
+- [Shell Autocompletion](#shell-autocompletion)
+
+### Linux and MacOs
+
+#### Homebrew
+
+If you have [Homebrew] installed on your system `vab` is only a command away:
+
+```sh
+brew install mia-platform/tap/vab
+```
+
+#### Go
+
+If you have [Golang] installed with a version >= 1.13 in your system and you have the `$GOPATH`env set, you can
+install `vab` like this:
+
+```sh
+go install github.com/mia-platform/vab/cmd/[email protected]
+```
+
+Or like this if the `install` command is not available
+
+```sh
+go get -u github.com/mia-platform/vab/cmd/[email protected]
+```
+
+#### Binary Download
+
+You can install `vab` with the use of `curl` or `wget` and downloading the latest packages available on GitHub
+choosing the correct platform and operating system:
+
+```sh
+curl -fsSL https://github.com/mia-platform/vab/releases/download/v0.9.0/vab-linux-amd64 -o /tmp/vab
+```
+
+```sh
+wget -q https://github.com/mia-platform/vab/releases/download/v0.9.0/vab-linux-amd64 -O /tmp/vab
+```
+
+After you have downloaded the file you can validate it against the checksum you can find at this [url] running the
+command:
+
+```sh
+sha256sum /tmp/vab
+```
+
+After you have validated that the downloaded file is correct, move the binary in your `/usr/local/bin` folder
+
+```sh
+sudo install -g root -o root /tmp/vab /usr/local/bin
+```
+
+#### Docker
+
+If you want to run the cli in its environment or you want to test the cli you can use the Docker image:
+
+```sh
+docker run ghcr.io/mia-platform/vab:0.9.0
+```
+
+### Windows
+
+`vab` is not directly compatible with Windows, even if you have Go installed compilation on this OS
+is not possible due to current technical restrictions.
+
+However, it is still possible to use `vab` with Windows Subsystem for Linux (WSL), as explained here below.
+
+#### Installation of WSL
+
+If you don't have WSL on your system, follow the [official guide] to get it.
+
+Once WSL is installed, to open a Linux bash terminal, press Start+R, enter `bash` in the text box and press OK.
+
+#### Install `vab`
+
+You can now install vab with any of the methods explained above for Linux,
+we suggest the [binary installation](#binary-download) since it's the most straightforward.
+
+## Shell Autocompletion
+
+If you have choosen to use an installation method different from the brew one, you will have to setup the
+commands autocompletion for your shell following one of these guides:
+
+- [`bash`](#bash)
+- [`zsh`](#zsh)
+- [`fish`](#fish)
+
+When you update the command remember to relaunch the command for your shell to update the completion definition
+and get the latest command and/or flags that has been added.
+
+### `bash`
+
+The `bash` autocompletion needs the [`bash-completion`] package installed on your system.
+
+**Warning:** for working correctly you need the `bash-completion` V2 that is compatible only with Bash 4.1+,
+please be sure to have the correct versions installed on your system before running the command.
+
+```sh
+vab completion bash >/usr/local/etc/bash_completion.d/vab
+```
+
+After done this you must restart your shell environment or launch `exec bash` for reloading the configurations
+and enable the autocompletion.
+
+### `zsh`
+
+For setting up the `zsh` completion, you must enable it. You can use the following command:
+
+```sh
+echo "autoload -U compinit; compinit" >> ~/.zshrc
+```
+
+Or use something like [`oh-my-zsh`] that will enable it by default. Once you have done it you can launch the
+following command to create the file needed by `zsh`:
+
+```sh
+vab completion zsh > /usr/local/share/zsh/site-functions/_vab
+```
+
+After done this you must restart your shell environment or launch `exec zsh` for reloading the configurations and
+enable the autocompletion.
+
+### `fish`
+
+To enable the autocompletion in `fish` you have to run this command:
+
+```sh
+vab completion fish > ~/.config/fish/completions/vab.fish
+```
+
+After done this you must restart your shell environment or launch `exec fish` for reloading the configurations and
+enable the autocompletion.
+
+[Homebrew]: https://brew.sh "The Missing Package Manager for macOS (or Linux)"
+[Golang]: https://go.dev "Build simple, secure, scalable systems with Go"
+[url]: https://github.com/mia-platform/vab/releases/download/v0.12.2/checksums.txt "vab checksums"
+[`bash-completion`]: https://github.com/scop/bash-completion "Programmable completion functions for bash"
+[`oh-my-zsh`]: https://ohmyz.sh "Oh My Zsh is a delightful, open source, community-driven
+	framework for managing your Zsh configuration"
+[official guide]: https://learn.microsoft.com/en-us/windows/wsl/install "How to install Linux on Windows with WSL"