diff --git a/.makim.yaml b/.makim.yaml index c4f2e33..18217fe 100644 --- a/.makim.yaml +++ b/.makim.yaml @@ -24,11 +24,12 @@ groups: build: help: Build documentation run: | - mkdocs build --config-file docs/mkdocs.yaml + mkdocs build --config-file mkdocs.yaml preview: help: Preview documentation page locally - run: mkdocs serve --watch docs --config-file docs/mkdocs.yaml + run: | + mkdocs serve --watch docs --config-file mkdocs.yaml release: vars: diff --git a/README.md b/README.md index 123446f..fad2b3f 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,37 @@ -# MakIm +# Get Started -`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. +`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 idea of this project is to offer a way to define targets and -dependencies with some control options, like conditionals `if`. +The idea of this project is to offer a way to define targets and dependencies +with some control options, like conditionals `if`. -It allows a very easy way to define texts for documentation and -extra parameters for each target. +It allows a very easy way to define texts for documentation and extra parameters +for each target. - -* Free software: BSD 3 Clause -* Documentation: https://osl-incubator.github.io/makim +- License: BSD 3 Clause +- Documentation: https://osl-incubator.github.io/makim ## Features -* Help text as first-class in the `.makim.yaml` specification. It can be used by targets and arguments. -* Targets have an option for arguments. -* Targets have an option for dependencies. -* Dependencies can call a target with specific arguments. -* Dependencies can have a conditional control flow (`if`). -* Allow the creation of groups, so the targets can be organized by topics. -* Targets 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 in the `.makim.yaml` specification. It can be used by + targets and arguments. +- Targets have an option for arguments. +- Targets have an option for dependencies. +- Dependencies can call a target with specific arguments. +- Dependencies can have a conditional control flow (`if`). +- Allow the creation of groups, so the targets can be organized by topics. +- Targets 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. ## 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: +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 @@ -64,15 +66,11 @@ groups: Some examples of how to use it: -* run the `build` target: - `makim build` - -* run the `clean` target: - `makim clean` +- run the `build` target: `makim build` -* run the `build` target with the `clean` flag: - `makim build --clean` +- run the `clean` target: `makim clean` +- run the `build` target with the `clean` flag: `makim build --clean` The help menu for the `.makim.yaml` file would looks like this: @@ -84,15 +82,16 @@ 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: + 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. - NOTE: 'default.' prefix is optional. options: --help, -h @@ -105,59 +104,5 @@ options: 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. - -## Xonsh Shell Integration - -### What is Xonsh? -[Xonsh](https://xon.sh/) is a powerful shell language and command prompt designed to -seamlessly blend traditional shell capabilities with the expressive syntax of Python. - It offers an interactive and extensible environment that enables users to transition - effortlessly between standard shell commands and Python scripting. - -### How Xonsh enhances this Project? -In the context of this project, Xonsh serves as the default shell for executing commands -defined in the Makim configuration. By leveraging Xonsh, the Makim tool gains the flexibility -and richness of the Python programming language within a command-line interface. This integration -allows users to create sophisticated tasks and harness the full power of Python directly -in the terminal. - -### Key Features and Commands in Xonsh -1. **Unified Syntax :** Xonsh seamlessly integrates traditional shell syntax with Python's -clean and expressive syntax, creating a unified and consistent scripting experience. -``` -# Shell-style command -ls -l - -# Python-style variable assignment -$filename = "example.txt" - -# Combining both in a single command -echo "The contents of $filename are: $(cat $filename)" -``` - -2. **Python Variables and Expressions :** Python variables can be easily incorporated into -commands, enhancing the readability and flexibility of your scripts. -``` -$filename = "example.txt" -echo "The filename is $filename" -``` - -3. **Looping and Conditional Statements :** Use Python-style loops and conditionals to create -dynamic and complex command sequences. -``` -for $i in range(3): - echo "Iteration $i" -``` - -4. **Extensible Tab Completion :** Xonsh offers extensible and intelligent tab completion, -making it easier to discover and complete commands and variables. -``` -$long_variable_name = "some_value" -echo $long_ -# Xonsh will intelligently complete the variable name -``` - -For more comprehensive information and documentation, explore the [Xonsh GitHub repository] -(https://github.com/xonsh/xonsh) and the official [Xonsh website](https://xon.sh/). +As you can see, the help menu automatically adds information defined by all the +`help` key, inside the `.makim.yaml` file. diff --git a/artwork/poc/favicon.svg b/artwork/poc/favicon.svg new file mode 100644 index 0000000..36ed1de --- /dev/null +++ b/artwork/poc/favicon.svg @@ -0,0 +1,157 @@ + + + + diff --git a/artwork/poc/logo.svg b/artwork/poc/logo.svg new file mode 100644 index 0000000..0eb6c07 --- /dev/null +++ b/artwork/poc/logo.svg @@ -0,0 +1,66 @@ + + + + diff --git a/artwork/v1/favicon.png b/artwork/v1/favicon.png new file mode 100644 index 0000000..310ff97 Binary files /dev/null and b/artwork/v1/favicon.png differ diff --git a/artwork/v1/logo.png b/artwork/v1/logo.png new file mode 100644 index 0000000..31f11b4 Binary files /dev/null and b/artwork/v1/logo.png differ diff --git a/docs/contributing.md b/docs/contributing.md index 9ceabb1..5a6af0a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,7 +1,7 @@ # Contributing -Contributions are welcome, and they are greatly appreciated! Every -little bit helps, and credit will always be given. +Contributions are welcome, and they are greatly appreciated! Every little bit +helps, and credit will always be given. You can contribute in many ways: @@ -13,27 +13,24 @@ Report bugs at https://github.com/osl-incubator/makim.git/issues. If you are reporting a bug, please include: - - Your operating system name and version. - - Any details about your local setup that might be helpful in - troubleshooting. - - Detailed steps to reproduce the bug. +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting. +- Detailed steps to reproduce the bug. ### Fix Bugs -Look through the GitHub issues for bugs. Anything tagged with “bug” and -“help wanted” is open to whoever wants to implement it. +Look through the GitHub issues for bugs. Anything tagged with “bug” and “help +wanted” is open to whoever wants to implement it. ### Implement Features -Look through the GitHub issues for features. Anything tagged with -“enhancement” and “help wanted” is open to whoever wants to implement -it. +Look through the GitHub issues for features. Anything tagged with “enhancement” +and “help wanted” is open to whoever wants to implement it. ### Write Documentation -makim could always use more documentation, -whether as part of the official makim docs, -in docstrings, or even on the web in blog posts, articles, and such. +makim could always use more documentation, whether as part of the official makim +docs, in docstrings, or even on the web in blog posts, articles, and such. ### Submit Feedback @@ -42,59 +39,73 @@ https://github.com/osl-incubator/makim.git/issues. If you are proposing a feature: - - Explain in detail how it would work. - - Keep the scope as narrow as possible, to make it easier to - implement. - - Remember that this is a volunteer-driven project, and that - contributions are welcome :) +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. +- Remember that this is a volunteer-driven project, and that contributions are + welcome :) ## Get Started! -For development, we encourage you to use `conda`. If you don't know -what is that, check these links: +For development, we encourage you to use `conda`. If you don't know what is +that, check these links: -* In Spanish: https://opensciencelabs.org/blog/como-instalar-y-comenzar-utilizar-conda/ -* In English: https://cloudsmith.com/blog/what-is-conda/ +- In Spanish: + https://opensciencelabs.org/blog/como-instalar-y-comenzar-utilizar-conda/ +- In English: https://cloudsmith.com/blog/what-is-conda/ -We recommend you to use mamba-forge, a combination of -miniconda + conda-forge + mamba. You can download it from here: +We recommend you to use mamba-forge, a combination of miniconda + conda-forge + +mamba. You can download it from here: https://github.com/conda-forge/miniforge#mambaforge Ready to contribute? Here’s how to set up `makim` for local development. 1. Fork the `makim` repo on GitHub. 2. Clone your fork locally: + ```bash $ git clone git@github.com:your_name_here/makim.git ``` + 3. Create a conda environment and activate it: + ```bash $ mamba env create --file conda/dev.yaml ``` + and + ```bash $ conda activate makim ``` + 4. Install your local project copy into your conda environment: + ```bash $ poetry install ``` + 5. Create a branch for local development:: + ```bash $ git checkout -b name-of-your-bugfix-or-feature ``` -6. When you’re done makimg changes, check that your changes pass flake8 - and the tests, including testing other Python versions with tox:: + +6. When you’re done makimg changes, check that your changes pass flake8 and the + tests, including testing other Python versions with tox:: + ```bash $ makim tests.linter $ makim tests.unittest $ makim tests.smoke ``` + 7. Commit your changes and push your branch to GitHub:: + ```bash $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature ``` + 8. Submit a pull request through the GitHub website. ## Pull Request Guidelines @@ -102,9 +113,9 @@ $ git push origin name-of-your-bugfix-or-feature Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. -2. If the pull request adds functionality, the docs should be updated. - Put your new functionality into a function with a docstring, and add - the feature to the list in README.rst. +2. If the pull request adds functionality, the docs should be updated. Put your + new functionality into a function with a docstring, and add the feature to + the list in README.rst. 3. The pull request should work for Python >= 3.8. ## Tips @@ -117,42 +128,42 @@ $ pytest tests.test_containers_sugar ## Release -This project uses semantic-release in order to cut a new release -based on the commit-message. +This project uses semantic-release in order to cut a new release based on the +commit-message. ### Commit message format -**semantic-release** uses the commit messages to determine the consumer -impact of changes in the codebase. Following formalized conventions for -commit messages, **semantic-release** automatically determines the next +**semantic-release** uses the commit messages to determine the consumer impact +of changes in the codebase. Following formalized conventions for commit +messages, **semantic-release** automatically determines the next [semantic version](https://semver.org) number, generates a changelog and publishes the release. -By default, **semantic-release** uses [Angular Commit Message -Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). -The commit message format can be changed with the `preset` or `config` -options_ of the +By default, **semantic-release** uses +[Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). +The commit message format can be changed with the `preset` or `config` options\_ +of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins. Tools such as [commitizen](https://github.com/commitizen/cz-cli) or -[commitlint](https://github.com/conventional-changelog/commitlint) can -be used to help contributors and enforce valid commit messages. +[commitlint](https://github.com/conventional-changelog/commitlint) can be used +to help contributors and enforce valid commit messages. -The table below shows which commit message gets you which release type -when `semantic-release` runs (using the default configuration): +The table below shows which commit message gets you which release type when +`semantic-release` runs (using the default configuration): | Commit message | Release type | -|----------------------------------------------------------------|------------------| +| -------------------------------------------------------------- | ---------------- | | `fix(pencil): stop graphite breaking when pressure is applied` | Fix Release | | `feat(pencil): add 'graphiteWidth' option` | Feature Release | | `perf(pencil): remove graphiteWidth option` | Chore | -| `BREAKING CHANGE: The graphiteWidth option has been removed` | Breaking Release | +| `feat(pencil)!: The graphiteWidth option has been removed` | Breaking Release | source: -As this project uses the `squash and merge` strategy, ensure to apply -the commit message format to the PR's title. +As this project uses the `squash and merge` strategy, ensure to apply the commit +message format to the PR's title. diff --git a/docs/images/android-chrome-192x192.png b/docs/images/android-chrome-192x192.png new file mode 100644 index 0000000..74b729c Binary files /dev/null and b/docs/images/android-chrome-192x192.png differ diff --git a/docs/images/android-chrome-512x512.png b/docs/images/android-chrome-512x512.png new file mode 100644 index 0000000..5f56766 Binary files /dev/null and b/docs/images/android-chrome-512x512.png differ diff --git a/docs/images/apple-touch-icon.png b/docs/images/apple-touch-icon.png new file mode 100644 index 0000000..93f059c Binary files /dev/null and b/docs/images/apple-touch-icon.png differ diff --git a/docs/images/favicon-16x16.png b/docs/images/favicon-16x16.png new file mode 100644 index 0000000..ab50031 Binary files /dev/null and b/docs/images/favicon-16x16.png differ diff --git a/docs/images/favicon-32x32.png b/docs/images/favicon-32x32.png new file mode 100644 index 0000000..27c1ca5 Binary files /dev/null and b/docs/images/favicon-32x32.png differ diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico index c264835..8ec500d 100644 Binary files a/docs/images/favicon.ico and b/docs/images/favicon.ico differ diff --git a/docs/images/logo.png b/docs/images/logo.png index e80a40e..31f11b4 100644 Binary files a/docs/images/logo.png and b/docs/images/logo.png differ diff --git a/docs/images/site.webmanifest b/docs/images/site.webmanifest new file mode 100644 index 0000000..1dd9112 --- /dev/null +++ b/docs/images/site.webmanifest @@ -0,0 +1 @@ +{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"} diff --git a/docs/installation.md b/docs/installation.md index 5242a36..9fc9d48 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -2,24 +2,25 @@ ## Stable release -To install makim, run this command in your -terminal: +To install makim, run this command in your terminal: ```bash $ pip install makim ``` -This is the preferred method to install makim, -as it will always install the most recent stable release. +Makim is also available on conda-forge: -If you don't have [pip](https://pip.pypa.io) installed, this -[Python installation guide](http://docs.python-guide.org/en/latest/starting/installation/) -can guide you through the process. +```bash +$ conda install -c conda-forge makim +``` + +This is the preferred method to install makim, as it will always install the +most recent stable release. ## From sources -The sources for makim can be downloaded from -the [Github repo](https://github.com/osl-incubator/makim.git). +The sources for makim can be downloaded from the +[Github repo](https://github.com/osl-incubator/makim.git). You can either clone the public repository: @@ -34,8 +35,8 @@ Or download the $ curl -OJL https://github.com/osl-incubator/makim.git/tarball/main ``` -Once you have a copy of the source, change to the project root directory -and install it with: +Once you have a copy of the source, change to the project root directory and +install it with: ```bash $ poetry install diff --git a/docs/xonsh.md b/docs/xonsh.md new file mode 100644 index 0000000..c2ba339 --- /dev/null +++ b/docs/xonsh.md @@ -0,0 +1,60 @@ +# Xonsh Shell Integration + +In the context of this project, Xonsh serves as the default shell for executing +commands defined in the Makim configuration. By leveraging Xonsh, the Makim tool +gains the flexibility and richness of the Python programming language within a +command-line interface. This integration allows users to create sophisticated +tasks and harness the full power of Python directly in the terminal. + +## What is Xonsh? + +[Xonsh](https://xon.sh/) is a powerful shell language and command prompt +designed to seamlessly blend traditional shell capabilities with the expressive +syntax of Python. It offers an interactive and extensible environment that +enables users to transition effortlessly between standard shell commands and +Python scripting. + +## Key Features and Commands in Xonsh + +1. **Unified Syntax :** Xonsh seamlessly integrates traditional shell syntax + with Python's clean and expressive syntax, creating a unified and consistent + scripting experience. + +``` +# Shell-style command +ls -l +# Python-style variable assignment +$filename = "example.txt" +# Combining both in a single command +echo "The contents of $filename are: $(cat $filename)" +``` + +2. **Python Variables and Expressions :** Python variables can be easily + incorporated into commands, enhancing the readability and flexibility of your + scripts. + +``` +$filename = "example.txt" +echo "The filename is $filename" +``` + +3. **Looping and Conditional Statements :** Use Python-style loops and + conditionals to create dynamic and complex command sequences. + +``` +for $i in range(3): + echo "Iteration $i" +``` + +4. **Extensible Tab Completion :** Xonsh offers extensible and intelligent tab + completion, making it easier to discover and complete commands and variables. + +``` +$long_variable_name = "some_value" +echo $long_ +# Xonsh will intelligently complete the variable name +``` + +For more comprehensive information and documentation, explore the [Xonsh GitHub +repository] (https://github.com/xonsh/xonsh) and the official +[Xonsh website](https://xon.sh/). diff --git a/docs/mkdocs.yaml b/mkdocs.yaml similarity index 94% rename from docs/mkdocs.yaml rename to mkdocs.yaml index 3e70af8..2b1788a 100644 --- a/docs/mkdocs.yaml +++ b/mkdocs.yaml @@ -1,8 +1,8 @@ -site_name: makim +site_name: Makim site_url: https://osl-incubator.github.io/makim repo_url: https://github.com/osl-incubator/makim.git -docs_dir: ./ -site_dir: ../build +docs_dir: ./docs +site_dir: ./build # extra_css: # - stylesheets/extra.css theme: @@ -19,7 +19,7 @@ theme: icon: repo: fontawesome/brands/github logo: ./images/logo.png - favicon: ./images/favicon.png + favicon: ./images/favicon.ico palette: scheme: slate primary: white @@ -113,7 +113,7 @@ markdown_extensions: - tables - toc extra: - project_name: "makim" + project_name: "Makim" team: - name: "Active maintainers" members: @@ -123,7 +123,7 @@ extra: - xmnlab social: - icon: fontawesome/brands/twitter - link: https://twitter.com/xmnlab + link: https://twitter.com/opensciencelabs - icon: fontawesome/brands/github link: https://github.com/osl-incubator/makim.git support_levels: @@ -137,4 +137,4 @@ extra: icon: :material-cancel:{ .cancel } description: Unlikely to ever be supported or no upstream support. -copyright: "Copyright © 2022, makim Team" +copyright: "Copyright © 2022, Makim Team" diff --git a/src/makim/cli.py b/src/makim/cli.py index 1a13090..3c6820e 100644 --- a/src/makim/cli.py +++ b/src/makim/cli.py @@ -46,9 +46,9 @@ def _get_args(): makim_file_default = str(Path(os.getcwd()) / '.makim.yaml') parser = argparse.ArgumentParser( - prog='MakIm', + prog='Makim', description=( - 'MakIm is a tool that helps you to organize ' + 'Makim is a tool that helps you to organize ' 'and simplify your helper commands.' ), epilog=( @@ -68,7 +68,7 @@ def _get_args(): parser.add_argument( '--version', action='store_true', - help='Show the version of the installed MakIm tool.', + help='Show the version of the installed Makim tool.', ) parser.add_argument( diff --git a/src/makim/makim.py b/src/makim/makim.py index 9a76b58..9946f13 100644 --- a/src/makim/makim.py +++ b/src/makim/makim.py @@ -1,7 +1,7 @@ """ Makim main class. -`MakIm` or just `makim` is based on `make` and focus on improve +`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. """