WIP Docs/rewrite readme

README.md

@@ -1,104 +1,102 @@
 # Exeiac
 
-## Description
-`exeiac` is a tool that enables infrastructure folks to handle several
-different provisionning IaC (Infrastructure as Code) tools, under a
-single CLI, and helps solving some recurrent paintpoints with IaC.
+## Why use exeIaC
+`exeiac` is a tool that enables infrastructure folks to handle several 
+different provisioning IaC (Infrastructure as Code) tools under a single CLI 
+and helps solve some recurrent pain points with IaC.
 
-It follows the brick convention, which describes an infrastructure as
-a set of bricks. A brick is a piece of infrastructure, it
-simultaneously is the actual infrastructure element, the code that
-describes it and a piece code that allows its execution; be it a
-terraform state, an ansible playbook or a helm chart for instance.
+It follows the brick convention, which describes an infrastructure as a set of 
+bricks. A brick is a piece of infrastructure; it simultaneously is the actual 
+infrastructure element, the code that describes it, and a piece of code that 
+allows its execution; be it a terraform state, an ansible playbook, or a helm 
+chart, for instance.
 
 This project was born from the following needs:
 - solve dependencies issues
-- increase transparency as to how a piece of infrastructure should be
-    deployed. No matter the provisionning tool you use, if there's a
-    module for it, `exeiac` will handle it
-- allow for a clean way to interact with only a part of your
-  infrastructure in a safe way, without breaking the dependency tree,
-  even if your infrastructure management tool doesn't provide that
-  feature
+- increase transparency as to how a piece of infrastructure should be deployed. 
+  No matter the provisioning tool you use, if there's a module for it, `exeiac` 
+  will handle it
+- allow for a clean way to interact with only a part of your infrastructure in 
+  a safe way, without breaking the dependency tree, even if your infrastructure 
+  management tool doesn't provide that feature
 
-## DOCUMENTATION
+## What is a brick
+First, exeIaC deals with infra bricks. What is an infra brick? Basically, it's 
+a directory that contains some infra code. It can be a terraform directory to 
+deploy a VM, an ansible playbook to configure a host, a helm chart, or simply a 
+template that describes some instructions to do manually.
 
-- philosophy: theoretical approach useful to write your infra code and understand
-  exeiac best practices
-  - common infra code problems we try to solve with exeiac
-  - define infra as a set of bricks
-  - define the brick concept
-  - explain how bricks depends of each other
-  - vocabulary
-- development: contain specs and schema to understand how it is coded
-- user: contain all you need to use the tool and create an infra code that
-  respect the convention and best practices
-- examples: examples of simple infra code and module
+This summary should be enough for you to be able to read the following 
+paragraphs and have a basic understanding of exeIaC. But if you want to get a 
+better grasp of the brick concept itself and its genius simplicity, you can 
+find a deeper insight on 
+[this documentation page](./docs/brick_concept_and_dependencies).
 
 ## Get started
 
-### Installation
-
-Clone the git repository and build:
-``` bash
-$ git clone github.com/arthur91f/exeiac/src/exeiac
-$ cd exeiac
-$ go install src/exeiac
-```
+- **1. Get exeiac binary and install completion**
+  ```bash
+  asdf plugin add golang https://github.com/asdf-community/asdf-golang.git
+  asdf install golang 1.19
+  git clone https://github.com/arthur91f/exeiac.git
+  cd exeiac/
+  asdf local golang 1.19
+  go install src/exeiac
+  ```
+  - bash completion:  `cp './src/completion/scripts/exeiac.sh' '/usr/share/bash-completion/completions/exeiac'`
+  - zsh completion: `cp './src/completion/scripts/exeiac.zsh' '/usr/share/zsh/site-functions/_exeiac'`
+  - fish completion: `cp './src/completion/scripts/exeiac.fish' '/usr/share/fish/vendor_completions.d/exeiac.fish'`
 
-There is no release process yet, but on Go version 1.16 or later you can:
-``` bash
-# Install at tree head:
-$ go install github.com/arthur91f/exeiac/src/exeiac/src/exeiac@main
-```
+- **2. Write your modules** in whatever language you want. A module can be seen 
+  as a makefile to deploy your brick. Basically, it's a shell script that 
+  follows some conventions described here: 
+  [How to write module](./docs/howto_write_module.md). You have to implement 
+  three commands:
+    - *describe_module_for_exeiac* (that displays a json)
+    - *lay* to deploy your brick
+    - *output* to display some specs of your brick such as IP address, login...
+    - ... you can implement other commands like plan, remove, lint, help...
 
-- get the exeiac binary
-- have an infra code that follow some conventions (see below for more details)
-  - each brick is a directory prefixed by a number to make the apply order
-    transparent
-  - each elementary brick should have a brick.yml to define how it will be
-    executed and the input it needed from dependencies
-  - each elementary brick should reference in brick.yml an executable or module
-    to execute itself. (a module is simply an executable that is not in the
-    brick directory and that can be called by many bricks)
-  - Read [howto_write_brick](./docs/howto_write_brick.md)
-- create a conf file in /etc/exeiac/exeiac.yml or $HOME/.config/exeiac.yml
-  ```yaml
-  modules_path:
-    terraform: $HOME/git-repos/exeiac-modules/terraform
-    ansible: $HOME/git-repos/exeiac-modules/terraform
-  room_paths_list:
-    - $HOME/git-repos/infra-ground
-    - $HOME/git-repos/applications
-    - $HOME/git-repos/users
-  ```
+- **3. Put a YAML file in each IaC directory** to describe your bricks as here 
+  [How to write brick](./docs/howto_write_brick.md). It will let:
+  - exeiac identify your IaC directory as an infra brick
+  - associate your brick to its module
+  - exeiac understand your brick's dependencies and how to present them to the 
+    brick
 
-### Simple command line examples
+- **4. Write your exeiac conf file** in your home or in /etc to let exeiac 
+  binary find your module and your infra code. 
+  [How to write config file](./docs/howto_write_configuration_file.md)
 
-- display a brick output
-  ```json
-  $ exeiac output ./infra-core/2-staging/2-ssh_bastion
-  {
-      "instance_id": "bastion-staging-221022",
-      "private_ip": "10.11.3.2",
-      "public_ip": "34.33.31.30"
-  }
-  ```
-- deploy a brick and recursively deploy all bricks that depends on an output
-  that have changed. Note that here we have used the brickname and not the path
-  ```bash
-  exeiac lay infra-core/staging/ssh_bastion --bricks-specifier=selected+needed_dependents
-  ```
-- destroy a higher level brick. It will destroy all elementary bricks
-  contained in the higher level bricks in the right order.
-  ```bash
-  exeiac remove infra-core/staging
-  ```
-- get more help
-  ```bash
-  exeiac help
-  ```
+- **5. Enjoy exeiac**
+  Here are some examples of basic commands you can execute:
+  - Display output of a brick
+    ```bash
+    exeiac output infra-ground/envs/staging/network
+    ```
+  - Plan all sub-bricks of infra-ground/envs/staging
+    ```bash
+    exeiac output infra-ground/envs/staging
+    ```
+  - Display all bricks that should be re-deployed after the change of the 
+    brick's network output .network.ip_range
+    ```bash
+    exeiac get-depends infra-ground/envs/staging/network -j $.network.ip_range
+    ```
+  - Display all bricks that can be impacted by the re-deploy of the brick network
+    ```bash
+    exeiac show infra-ground/envs/staging/network --bricks-specifiers linked_next --format name
+    ```
+  - Deploy/re-deploy a drift in brick staging/network and all other bricks 
+    impacted by that drift recursively.
+    ```bash
+    exeiac smart-lay infra-ground/envs/staging/network --non-interactive
+    ```
 
-### Create a module or an executable
+## Useful links
 
-Read [howto_write_module](./docs/howto_write_module.md)
+- **local**
+  - [How to join us](./docs/to_write.md)
+- **external**
+  - [Download exeiac](https://download-exeiac.91f.ovh)
+  - [exeIaC presentation](https://drive.google.com/blabla)