WIP

WIP documentation of features.

docs/features.md

@@ -1,87 +1,240 @@
-# Features
-
-## Attribute: working-directory
-
-The working-directory feature in Makim allows users to define the directory
-from which commands associated with specific targets or groups are executed.
-This provides greater flexibility and control over the execution environment.
-
-The `working-directory` attribute can be specified at three different
-scopes: global, group, and target. It allows users to set the working
-directory for a specific target, a group of targets, or globally.
-
-### Syntax and Scopes
-The working-directory attribute can be applied to three different scopes:
-
-- #### **Global Scope**
-    Setting the global working directory impacts all targets and groups in
-    the Makim configuration.
-
-    ```yaml
-    version: 1.0
-    working-directory: /path/to/global/directory
-
-    # ... other configuration ...
-    ```
-
-- #### Group Scope
-
-    Setting the working directory at the group scope affects all targets within
-    that group.
-
-    ```yaml
-
-    version: 1.0
-
-    groups:
-        my-group:
-            working-directory: /path/to/group/directory
-            targets:
-                target-1:
-                    run: |
-                    # This target will run with the working directory set to
-                    # /path/to/group/directory
-    ```
-
-- #### Target Scope
-
-    Setting the working directory at the target scope allows for fine grained
-    control over individual targets.
-
-    ```yaml
-    version: 1.0
-    groups:
-        my-group:
-            targets:
-                my-target:
-                    working-directory: /path/to/target/directory
-                    run: |
-                    # This target will run with the working directory set to
-                    # /path/to/target/directory
-    ```
-
-## Example
-
-```yaml
-version: 1.0
-working-directory: /project-root
-
-groups:
-  backend:
-    working-directory: backend
-    targets:
-      build:
-        help: Build the backend services
-        working-directory: services
-        run: |
-          echo "Building backend services..."
-          # Additional build commands specific to the backend
-
-      test:
-        help: Run backend tests
-        working-directory: tests
-        run: |
-          echo "Running backend tests..."
-          # Additional test commands specific to the backend
-
-```
+## version: 1.0
+
+# Groups
+
+## Default
+
+### makim env-file
+
+A .env file is a configuration file that defines environment-specific variables. It is written in YAML (YAML Ain't Markup Language). 
+
+You can use multiple .env files in your compose.yml with the env_file attribute. If the same variable is defined in multiple files, the last definition takes precedence:
+
+The `env-file` attribute can be specified at three different
+scopes: global, group, and target. It allows users to set the working
+scope for a specific target, a group of targets, or globally.]
+
+### Makim's env file is stored at       
+tests/.makim-env.yaml
+
+```
+makim/tests/.makim-env.yaml
+```
+
+### Syntax and Scopes
+The env-file attribute can be applied to three different scopes:
+
+- #### **Global Scope**
+    Setting the global env-file impacts all targets and groups in
+    the Makim configuration. This env-file works universally in that program.
+
+    ```yaml
+    global-scope:
+    targets:
+      test-var-env-file:
+        help: Test env variable defined in the global scope from env-file
+        run: |
+          import os
+          assert str(os.getenv("ENV")) == "dev"
+      test-var-env:
+        help: Test env variable defined in the global scope in `env` section
+        run: |
+          import os
+          assert str(os.getenv("GLOBAL_VAR_1")) == "1"
+          assert str(os.getenv("GLOBAL_VAR_2")) == "2"
+    ```
+
+- #### Group Scope
+    env-file can also have group scope.
+    Setting the env-file at the group scope affects all targets within  that group.
+    This file only works for the specified group.
+
+    ```yaml
+
+    group-scope:
+    env-file: .env-group
+    env:
+      GROUP_VAR_1: 1
+      GROUP_VAR_2: 2
+    targets:
+      test-var-env-file:
+        help: Test env variable defined in the global scope from env-file
+        run: |
+          import os
+          assert str(os.getenv("ENV")) == "prod"
+
+      test-var-env:
+        help: Test env variable defined in the global scope in `env` section
+        run: |
+          import os
+          assert str(os.getenv("GROUP_VAR_1")) == "1"
+          assert str(os.getenv("GROUP_VAR_2")) == "2"
+    
+    ```
+
+- #### Target Scope
+
+    Setting the env-file scope at the target allows for fine grained
+    control over individual targets.
+
+
+
+## Example
+
+```yaml
+version: 1.0
+working-directory: /project-root
+
+groups:
+  target-scope:
+    targets:
+      test-var-env-file:
+        help: Test env variable defined in the global scope from env-file
+        env-file: .env-target
+        run: |
+          import os
+          assert str(os.getenv("ENV")) == "test"
+
+      test-var-env:
+        help: Test env variable defined in the global scope in `env` section
+        env-file: .env-target
+        env:
+          TARGET_VAR_1: 1
+          TARGET_VAR_2: 2
+          ENV: staging
+        run: |
+          import os
+          assert str(os.getenv("TARGET_VAR_1")) == "1"
+          assert str(os.getenv("TARGET_VAR_2")) == "2"
+          assert str(os.getenv("ENV")) == "staging"
+
+
+```
+
+# targets:
+
+## TARGET-NAME
+
+### Attribute: help clean
+ 
+ We can simply remove the unneccessary file using the target commands:
+ - run the clean target: makim clean
+- run the build target with the clean flag: makim build --clean
+
+We can use the default selected target and use the clean command with our default target.
+  - default.clean => Use this target to clean up temporary files.
+     - ARGS:
+          --all: (bool) Remove all files that are tracked by git.
+
+
+### Arguments
+Arguments can be defined in a `args` section for each target and they can have different types (-all, --clean etc)
+The help menu for the .makim.yaml file contains the possible args 
+you can use:
+
+--all
+This arg is used in `default.clean` target. It removes all  the temporary files that are not tracked by git.
+
+--clean 
+This bool  arg is used in `default.build` is used to clean the unnecessary file after build.
+
+Both --args are bool type, which if not set will not be trigerred.
+
+The help menu for the .makim.yaml file would looks like this:
+
+```yaml
+   $ makim --help
+usage: MakIm [--help] [--version] [--config-file MAKIM_FILE] [target]
+
+MakIm is a tool that helps you to organize and simplify your helper commands.
+
+positional arguments:
+  target
+    Specify the target command to be performed. Options are:
+
+    default:
+    --------
+      default.clean => Use this target to clean up temporary files
+        ARGS:
+          --all: (bool) Remove all files that are tracked by git
+      default.build => Build the program
+        ARGS:
+          --clean: (bool) if not set, the clean dependency will not be triggered.
+
+options:
+  --help, -h
+    Show the help menu
+  --version
+    Show the version of the installed MakIm tool.
+  --config-file MAKIM_FILE
+    Specify a custom location for the config file.
+
+If you have any problem, open an issue at: https://github.com/osl-incubator/makim
+```
+
+As you can see, the help menu automatically adds information defined by all the help key, inside the .makim.yaml file.
+
+.### Attribute: Run
+MakIm or just makim is based on make and focus on improve the way to define targets and dependencies. Instead of using the Makefile format, it uses yaml format.
+
+The run atrributes in MakIm is used to run the build.
+
+
+### How to Run it
+First you need to place the config file .makim.yaml in the root of your project. This is an example of a configuration file:
+
+   ```yaml
+    version: 1.0.0
+groups:
+  default:
+    env-file: .env
+    targets:
+      clean:
+        help: Use this target to clean up temporary files
+        args:
+          all:
+            type: bool
+            action: store_true
+            help: Remove all files that are tracked by git
+        run: |
+          echo "remove file X"
+      build:
+        help: Build the program
+        args:
+          clean:
+            type: bool
+            action: store_true
+            help: if not set, the clean dependency will not be triggered.
+        dependencies:
+          - target: clean
+            if: {{ args.clean == true }}
+        run: |
+          echo "build file x"
+          echo "build file y"
+          echo "build file z"
+```
+Some examples of how to use it:
+
+- run the build target: makim build
+
+- run the clean target: makim clean
+
+- run the build target with the clean flag: makim build --clean
+
+### Attribute: dependencies
+
+ Makim needs the following directories to install and  run smoothly.
+
+- xonsh 
+- typing-extensions
+- sh
+- pyyaml 
+- python-dotenv
+- MarkupSafe 
+- colorama 
+- jinja2 
+- click 
+- typer.
+
+Genrally this is automatically handled when installing the makim. If there is is an existing  problem with your system 
+in any of this packages, makim may show errors. So make sure to resolve and install them.