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.

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

docs: Improve section Features with more makim features #80

Open
8 tasks
xmnlab opened this issue Jan 10, 2024 · 4 comments
Open
8 tasks

docs: Improve section Features with more makim features #80

xmnlab opened this issue Jan 10, 2024 · 4 comments
Labels
good first issue Good for newcomers psf-grant-proposal Issues used for a PSF grant proposal size:tiny <=2h

Comments

@xmnlab
Copy link
Member

xmnlab commented Jan 10, 2024

Currently https://osl-incubator.github.io/makim/features/ just has the documentation for one attribute: working-directory.

It would be nice to have a complete list of attributes and their documentation. It should be organized in a nested way, according to the .makim.yaml structure:

  • version
  • groups
    • default
      • env-file
      • targets:
        • TARGET-NAME
          • help: Use this target to clean up temporary files
          • args
          • run
          • dependencies

This would be a nice issue to tackle in order to get familiarized with makim.
the documentation file to be changed is this one: https://github.com/osl-incubator/makim/blob/main/docs/features.md

@xmnlab xmnlab added the good first issue Good for newcomers label Jan 10, 2024
@xmnlab
Copy link
Member Author

xmnlab commented Jan 10, 2024

@Tyagiquamar could you work on this issue please?

@Tyagiquamar
Copy link

@xmnlab it means that I have to change the features.md to add all the attributes?
I will try my best

@xmnlab
Copy link
Member Author

xmnlab commented Jan 10, 2024

yes please. thank you.

@xmnlab
Copy link
Member Author

xmnlab commented Feb 16, 2024

Example:

# MakIm Configuration File Reference

The `.makim.yaml` file is a central part of defining and managing your MakIm project configurations. This document outlines the structure and options available within a `.makim.yaml` file.

## Structure Overview

A `.makim.yaml` file is structured into several sections:

- `version`: Specifies the version of the MakIm file format.
- `env-file`: Specifies a global environment file.
- `shell`: Defines the default shell for running commands.
- `groups`: Organizes targets into named groups.
- `targets`: Defines the actions or commands that can be executed.
- `env`: Sets environment variables at different scopes.
- `dependencies`: Lists other targets that must be run before the current one.
- `working-directory`: Sets the working directory for the command execution.

### Version

Specifies the `.makim.yaml` file format version being used.

```yaml
version: 1.0
```

### Env-file

Specifies a path to an environment file that should be loaded before executing any commands.

```yaml
env-file: .env
```

### Shell

Defines the default shell for executing the commands. It can be overridden at the group or target level.

```yaml
shell: bash
```

### Groups

Organizes targets into named groups, allowing for structured and modular command definitions.

```yaml
groups:
  group-name:
    shell: bash
    env-file: .env-group
    env:
      VAR: "value"
    targets:
      target-name:
        # Target configuration
```

#### Group Configuration

- `shell`: Optionally override the global shell setting for all targets in the group.
- `env-file`: Specify a group-specific environment file.
- `env`: Define environment variables available to all targets within the group.

### Targets

Defines the actions or commands that can be executed. Targets can include arguments, dependencies, and specific run commands.

```yaml
targets:
  clean:
    help: "Remove all temporary files"
    run: |
      echo "Cleaning up..."
```

#### Target Configuration

- `help`: Provides a description of what the target does.
- `args`: Defines arguments that can be passed to the target.
- `dependencies`: Lists other targets that must be run before this one.
- `run`: The command(s) to be executed for this target.

### Env

Sets environment variables. These can be defined at the global level, within a group, or within a specific target.

```yaml
env:
  GLOBAL_VAR: "value"
```

### Dependencies

Specifies other targets that must be run before the current target. Dependencies can include conditions and arguments.

```yaml
dependencies:
  - target: another-target
    if: "{{ args.condition }}"
```

### Working-directory

Sets the working directory from which the command should be executed. This can be defined globally, for a group, or for a specific target.

```yaml
working-directory: "/path/to/directory"
```

## Examples

Here, provide comprehensive examples that demonstrate various features and configurations of `.makim.yaml` files. Show how to set up simple to complex workflows, utilize environment variables, define dependencies with conditions, and how to organize commands into groups.

@xmnlab xmnlab added psf-grant-proposal Issues used for a PSF grant proposal size:tiny <=2h labels Feb 16, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Good for newcomers psf-grant-proposal Issues used for a PSF grant proposal size:tiny <=2h
Projects
None yet
Development

No branches or pull requests

2 participants