Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Docs #132

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+809 −128
Open

Update Docs #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
43ab7d0
improve features.md file
abhijeetSaroha Jan 28, 2025
0eaaa3c
update readme.md file
abhijeetSaroha Jan 28, 2025
b5440e2
update docs
abhijeetSaroha Feb 3, 2025
dec99f6
add spec.md for .makim.yaml
abhijeetSaroha Feb 3, 2025
af4ecf3
update features.md
abhijeetSaroha Feb 7, 2025
e3b7a2a
update features.md
abhijeetSaroha Feb 7, 2025
51c4a69
add tutorial for ssh and scheduler
abhijeetSaroha Feb 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 69 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,97 +11,103 @@ It allows a very easy way to define texts for documentation and extra parameters
for each task.

- License: BSD 3 Clause
- Documentation: https://osl-incubator.github.io/makim
- Documentation: [Makim Docs](https://osl-incubator.github.io/makim)

---

## Features

- Help text as first-class in the `.makim.yaml` specification. It can be used by
tasks and arguments.
- Tasks have an option for arguments.
- Tasks have an option for dependencies.
- Dependencies can call a task with specific arguments.
- Dependencies can have a conditional control flow (`if`).
- Allow the creation of groups, so the tasks can be organized by topics.
- Tasks and groups have an option for user defined variables and/or environment
variables.
- Access arguments, variables or environment variables via template (using
Jinja2).
- Option for using dot environment files using `env-file` key.
- **Help Text as First-Class:** Add detailed `help` text to tasks and arguments
for clear documentation.
- **Task Arguments:** Define and manage arguments with types, defaults, and
descriptions.
- **Dependencies with Conditional Control:** Set task dependencies with `if`
conditionals to manage execution dynamically.
- **Environment Variables:** Scope variables globally, by group, or by task to
reduce redundancy and maintain modularity.
- **Jinja2 Templating:** Access arguments, variables, or environment variables
via Jinja2 templates.
- **Matrix Configuration:** Automate tasks across multiple parameter
combinations (ideal for CI/CD workflows).
- **Hooks:** Use `pre-run` and `post-run` hooks to customize task lifecycles.
- **Scheduler:** Cron-like scheduling with APScheduler integration for periodic
tasks.
- **Remote Execution:** Execute tasks on remote servers via SSH with flexible
configurations.
- **Validation:** Ensures `.makim.yaml` configurations are correct with schema
validation.

---

## How to use 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
build:
env:
GROUP_ENV: group_value
tasks:
clean:
help: Use this task to clean up temporary files
help: Clean build artifacts
args:
all:
cache:
type: bool
action: store_true
help: Remove all files that are tracked by git
help: Remove all cache files
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:
- task: clean
if: {% raw %}${{ args.clean == true }}{% endraw %}
echo "Cleaning build directory..."
rm -rf build/
compile:
help: Compile the project
hooks:
pre-run:
- task: clean # Run 'clean' before 'compile'
run: |
echo "build file x"
echo "build file y"
echo "build file z"
echo "Compiling the project..."

# Scheduler for automated tasks
scheduler:
daily-clean:
task: build.clean
schedule: "0 0 * * *" # Every day at midnight
```

Some examples of how to use it:

- run the `build` task: `makim build`

- run the `clean` task: `makim clean`
- run the `compile` task: `makim build.compile`

- run the `build` task with the `clean` flag: `makim build --clean`
- run the `clean` task with argument: `makim build.clean --cache`

The help menu for the `.makim.yaml` file would looks like this:

```
$ makim --help
usage: MakIm [--help] [--version] [--config-file MAKIM_FILE] [task]

MakIm is a tool that helps you to organize and simplify your helper commands.

positional arguments:
task
Specify the task command to be performed. Options are:

default:
--------
default.clean => Use this task 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

Usage: makim [OPTIONS] COMMAND [ARGS]...

Makim is a tool that helps you to organize and simplify your helper commands.

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version -v 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 Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ build ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ build.clean Clean build artifacts │
│ build.compile Compile the project │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Extensions ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ cron Tasks Scheduler │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

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
Expand Down
Loading
Loading