From a9abd486e5c7ea5b0a61df791bc0be5714a78d15 Mon Sep 17 00:00:00 2001 From: Mohd Quamar Tyagi <104281681+Tyagiquamar@users.noreply.github.com> Date: Tue, 30 Jan 2024 15:22:25 +0530 Subject: [PATCH 1/2] WIP WIP documentation of features. --- docs/features.md | 327 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 240 insertions(+), 87 deletions(-) diff --git a/docs/features.md b/docs/features.md index a7a282d..5fc5da9 100644 --- a/docs/features.md +++ b/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. \ No newline at end of file From da4e734886bde1f1d1f0aa9b121d95c1196f4fe3 Mon Sep 17 00:00:00 2001 From: Mohd Quamar Tyagi <104281681+Tyagiquamar@users.noreply.github.com> Date: Thu, 8 Feb 2024 19:08:02 +0530 Subject: [PATCH 2/2] WIP documentation of features. WIP documentation of features. Pull Request description Documentation of features this PR improves the feature documentation --- docs/features.md | 62 ++++++++++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/docs/features.md b/docs/features.md index 5fc5da9..95d8987 100644 --- a/docs/features.md +++ b/docs/features.md @@ -148,28 +148,44 @@ 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 +Options: + -v, --version Show the version and exit + --file TEXT Makim config file [default: .makim.yaml] + --dry-run Execute the command in dry mode + --verbose Execute the command in verbose mode + --install-completion [bash|zsh|fish|powershell|pwsh] + Install completion for the specified shell. + --show-completion [bash|zsh|fish|powershell|pwsh] + Show completion for the specified shell, to + copy it or customize the installation. + --help Show this message and exit. + +Commands: + clean.tmp Clean unnecessary... + docs.build Build documentation + docs.preview Preview documentation page... + release.ci Run semantic release on CI + release.dry Run semantic release in... + smoke-tests.bash Test makim shell attribute... + smoke-tests.complex Test makim using a complex... + smoke-tests.containers Test makim with... + smoke-tests.shell-app Test makim with... + smoke-tests.simple Test makim using a simple... + smoke-tests.unittest Test makim using a... + smoke-tests.vars-env Test makim using env... + smoke-tests.working-directory-absolute-path + Test makim with... + smoke-tests.working-directory-no-path + Test makim with... + smoke-tests.working-directory-relative-path + Test makim with... + tests.ci Run all targets used on CI + tests.linter Run linter tools + tests.smoke Run smoke tests + tests.unittest Run tests + + 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. @@ -221,7 +237,7 @@ Some examples of how to use it: - run the build target with the clean flag: makim build --clean -### Attribute: dependencies +## Attribute: dependencies Makim needs the following directories to install and run smoothly.