Merge pull request #93 from angulo-solido/91-add-mkdocs

Add missing stuff to Docs

docs/index.md

@@ -11,3 +11,10 @@
 ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/angulo-solido/terrabutler/Release%20Terrabutler?color=8956c4&logo=Github&style=for-the-badge)
 ![GitHub](https://img.shields.io/github/license/angulo-solido/terrabutler?color=8956c4&logo=Github&style=for-the-badge)
 ![GitHub Repo stars](https://img.shields.io/github/stars/angulo-solido/terrabutler?color=8956c4&label=Repo%20Stars&style=for-the-badge)
+
+---
+
+## What is Terrabutler?
+
+Terrabutler is a **wrapper** written in [Python](https://www.python.org/) that helps maintaining IaC (Infrastructure as code) projects
+using [Terraform](https://www.terraform.io/) by managing the **environments**.

docs/installation.md

@@ -0,0 +1,84 @@
+# Installation
+
+Before proceeding make sure that you have the [requirements](requirements.md).
+
+## Download the binaries and extract them
+
+All the binaries versions are available inside the [releases pages](https://github.com/angulo-solido/terrabutler/releases)
+
+To download the latest binaries run the following command:
+
+``` shell
+wget -qO- https://terrabutler-public.s3.amazonaws.com/releases/terrabutler-linux-x86_64-latest.tar.gz | tar -zxvf - terrabutler
+```
+
+???+ tip
+    If you wanna get a specific version just change the `<VERSION>` in the command below. All the **Terrabutler releases** are
+    available in the [repository releases pages](https://github.com/angulo-solido/terrabutler/releases)
+
+    ``` shell
+    wget -qO- https://terrabutler-public.s3.amazonaws.com/releases/terrabutler-linux-x86_64-<VERSION>.tar.gz | tar -zxvf - terrabutler
+    ```
+
+    For example, to download **Terrabutler v0.1.0**, just run:
+
+    ```
+    wget -qO- https://terrabutler-public.s3.amazonaws.com/releases/terrabutler-linux-x86_64-v0.1.0.tar.gz | tar -zxvf - terrabutler
+    ```
+
+## Install the binaries
+
+To install the binaries into your system simply run the installer script inside the `terrabutler` folder:
+
+``` shell
+sudo terrabutler/install
+```
+
+All the binaries will be placed inside the `/usr/share/terrabutler` folder and the bin inside the `/usr/bin` folder
+
+???+ tip
+    If you wanna set the location where terrabutler will be installed you can define it by passing arguments when running the install script.
+    This arguments can be seen by running:
+
+    ``` shell
+    terrabutler/install -h
+    ```
+
+    Example of installing for local user only **(no need to run the install script as sudo)**:
+
+    ``` shell
+    terrabutler/install -i ~/.local/share/terrabutler -b ~/.local/bin
+    ```
+
+## Check if the installation was successful
+
+You should be able to run:
+
+``` shell
+terrabutler --version
+```
+
+and the output should be:
+
+
+``` shell
+Terrabutler: v0.1.0
+```
+
+If the output is not similar to the one above, then **something went wrong during the installation**.
+
+## How to update to a newer version?
+
+If you have **Terrabutler** already installed and want to update to a newer version just do all the installation process again.
+When you will be running the installer script it should prompt if you want to upgrade the **Terrabutler**, as we can see below:
+
+``` shell
+Found preexisting Terrabutler installation: /usr/share/terrabutler.
+Do you want to replace it? [y/N]
+```
+
+Just press `y` and press *enter* and **Terrabutler** should be updated to the version that you downloaded.
+
+???+ danger
+    In case you have installed the **Terrabutler** earlier with different locations, you will need to pass them, otherwise the
+    install script **won't prompt** you to update it.

docs/philosophy.md

@@ -0,0 +1,22 @@
+# Philosophy
+
+Before settling for **Terrabutler**, it's a good idea to understand the philosophy behind the project,
+in order to make sure it aligns with your goals. This page explains the problem and the solution.
+
+## Problem
+
+All our IaC projects are backed by Terraform. Instead of having a folder with every resource, we have
+created different folders that have resources from the same category, and we call them `sites`. For
+example inside the `network site` we will have the creation of `VPC`, `SG` and `WAF`, so this site is
+where we have all the resources related to network. By splitting the code into various `sites` we have
+smaller plans and it's more easy to manage the code. By having all the code divided into various `sites`
+it's a bit more difficult to manage all the terraform variable files. And we wanted all of this for each
+**environment**, so it needs to be divided into different environments, for example production and development.
+All of the `sites` state needs to be have a remote state and with a lock function, to prevent usage at the same
+time.
+
+## Solution
+
+Create a IaC with the `inception site` that will be responsible to manage the project environments via Terraform
+workspaces tool and where the backends for each site will be created. Use **Terrabutler** to manage all the IAC
+between all the sites.

docs/requirements.md

@@ -0,0 +1,19 @@
+# Requirements
+
+Before you start using you will need to have some tools installed.
+
+- [direnv](https://direnv.net/)
+- [tfenv](https://github.com/tfutils/tfenv)
+
+These tools are required to be installed for a **Terrabutler** to work properly.
+
+## Installing requirements
+
+In the list below you have the install instruction for each tool:
+
+- [direnv](https://direnv.net/docs/installation.html)
+- [tfenv](https://github.com/tfutils/tfenv#installation)
+
+## After checking requirements
+
+You can now proceed to the [installation](installation.md) process of **Terrabutler**.

docs/usage.md

@@ -0,0 +1,93 @@
+# Basic Usage
+
+In this section we quickly cover the basic commands of **Terrabutler**.
+The usage of it can always be seen by using the help menu inside of every
+command or subcommand.
+
+Example:
+
+``` shell
+terrabutler tf -site inception apply --help
+```
+
+The command above shows all the arguments and options that can be used when
+running that command.
+
+## Usage 
+
+``` shell
+terrabutler [global options] command [subcommand] [arguments] [options]
+```
+
+## Global options
+
+All global options can be placed at the command level.
+
+* `--help`, `-help`, `-h`: Show help menu.
+* `--version`, `-version`: Show version of **Terrabutler**.
+
+## Commands
+
+The commands are:
+
+- `env`: Manage environments
+- `init`: Initialize the manager
+- `tf`: Manage terraform commands
+
+### Command `env`
+
+Subcommands:
+
+- `delete`: "Delete an environment"
+- `list`: "List environments"
+- `new`: "Create a new environment"
+- `select`: "Select a environment"
+- `show`: "Show the name of the current environment"
+
+Example:
+
+``` shell
+terrabutler env select staging
+```
+
+The command above change the current environment to `staging`.
+
+### Command `tf`
+
+???+ tip
+    The `tf` subcommands are the Terraform commands
+
+Subcommands:
+
+- `apply`: "Create or update infrastructure"
+- `console`: "Try Terraform expressions at an interactive command..."
+- `destroy`: "Prepare your working directory for other commands"
+- `fmt`: "Reformat your configuration in the standardstyle"
+- `force-unlock`: "Release a stuck lock on the current workspace"
+- `generate-options`: "Generate terraform options"
+- `import`: "Associate existing infrastructure with a Terraform..."
+- `init`: "Prepare your working directory for other commands"
+- `output`: "Show output values from your root module"
+- `plan`: "Show changes required by the current configuration"
+- `providers`: "Show the providers required for this configuration"
+- `refresh`: "Update the state to match remote systems"
+- `show`: "Show the current state or a saved plan"
+- `state`: "Advanced state management"
+- `taint`: "Mark a resource instance as not fully functional"
+- `untaint`: "Remove the 'tainted' state from a resource instance"
+- `validate`: "Validate the configuration files"
+- `version`: "Show the current Terraform version"
+
+Example:
+
+``` shell
+terrabutler tf -site inception apply
+```
+
+The command above run a `terraform apply` command inside the `site inception` in
+the current environment.
+
+### Command `init`
+
+Has no subcommands
+

mkdocs.yml

@@ -30,8 +30,20 @@ theme:
     repo: fontawesome/brands/github
 
 markdown_extensions:
+  - admonition
   - attr_list
+  - codehilite
   - md_in_html
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:materialx.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tabbed
 
 extra:
   social:
@@ -40,3 +52,7 @@ extra:
 
 nav:
   - Home: index.md
+  - Philosophy: philosophy.md
+  - Requirements: requirements.md
+  - Installation: installation.md
+  - Basic Usage: usage.md