Dev/86 better readme (#87)

* Update readme

* Bump project version

* Update Makefile

Author: piotr-rarus

Makefile

@@ -5,8 +5,6 @@ install_venv:
 install_pre_commit:
 	poetry run pre-commit install
 
-install_dev: install_venv install_pre_commit
-
 # Dev tools
 isort:
 	poetry run isort src
@@ -21,8 +19,6 @@ flake8:
 ruff:
 	poetry run ruff check src
 
-format: isort black
-
 mypy:
 	poetry run mypy --incremental --no-install-types --show-error-codes --pretty src
 
@@ -41,7 +37,13 @@ test_cov:
 compile_env:
 	poetry lock --no-update
 
-build: pre_commit ruff flake8 mypy test
+install_dev: install_venv install_pre_commit
+
+format: isort black
+
+lint: pre_commit ruff flake8 mypy
+
+build: pre_commit mypy test
 
 # Misc
 jupyter:

README.md

@@ -9,20 +9,81 @@
 [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
 
-This is a template repository dedicated to ML projects in python. It provides some basic tools and configs necessary to kickstart the development.
+Are you tired of dealing with messy code, debugging errors, and fixing bugs that could have been prevented with proper tools and practices? Do you want to improve the overall quality of your projects while saving time in the long run? Then this template is perfect for you!
+
+This is a template repository dedicated to ML projects in `Python`. It provides some basic tools and configs necessary to kickstart the development. It includes linting, type checking, package management, testing and CI.
+
+## Prerequisites
+
+In order to use this template, you need to have both `poetry` and `make` installed.
+
+### Poetry
+
+`poetry` is a package manager we're using. You can check the installation instructions [here](https://python-poetry.org/docs/#installing-with-the-official-installer). You should avoid installing `poetry` through `pip` as it is a system-level tool, separated from the `Python` runtime you're currently using. It enables us to treat `Python` as any other dependency and pin its version in `pyproject.toml`.
+
+```sh
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+### make
+
+`make` is a utility tool that enables us to create aliases for commands we type in the console to run programs. It's much more efficient to use `make` so you don't have to memorize console commands. You can also expose your project's CLI via `Makefile`.
+
+`make` should be available on most Linux distributions.
+
+If you're using Windows, I would get [choco](https://chocolatey.org/install) first, then get `make` from `choco` package gallery.
+
+```sh
+choco install make
+```
+
+Mac users can pull it using `Homebrew`.
+
+```sh
+brew install make
+```
+
+## Getting started
+
+To start your work, you need to set up your local environment and hooks.
+
+```sh
+make install_dev
+```
+
+Later you will define aliases for your CLI here. `Makefile` already contains calls to build tools and checks. Use `build` to run them all.
+
+```Makefile
+build: pre_commit mypy test
+```
+
+Please note that `build` does not encompass the coverage and dependencies updates. These need to be run separately. Coverage may not always be necessary and you're gonna be running `build` often while working locally. Updating dependencies should be approached with the utmost care, no reason to bump the versions all the time when code does the work it's intended for. Better use some automation tool like [dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file).
+
+To quickly format your repo while coding run:
+
+```sh
+make format  # isort black flake8
+```
+
+Before you commit, always run a full check. It's much faster to run it locally than to wait for CI build.
+
+```sh
+make build  # pre_commit mypy test
+```
 
 ## Structure
 
 - `.github` - CI/CD pipelines, usually named after repository host (`.github`, `.azure`, `.gitlab`, etc)
 - `data` - if you need any data to be present locally, store it here
-- `notebooks` - notebooks are particularly _meh_, but this is the directory to put them
+- `notebooks` - notebooks are kinda _meh_, but this is the directory to put them
 - `src` - here goes your project's code
 - `src/cli` - project's entry points should be wrapped with CLI and exposed via Makefile, good idea to store them separately
 - `.codespell` - whitelist for project-related terms
 - `.coveragearc` - coverage config, usually you don't want to report coverage on CLI, tests and some expressions
+- `.env.example` - here you should state any environment variables your project uses
 - `.pre-commit-config.yaml` - pre-commit pipeline configuration
 - `Makefile` - tasks definitions, much simpler to call `make` than writing whole commands in the terminal; it's also easy to check what project-specific functialities you're exposing
-- `mypy.ini` - `mypy` config, usually some of your dependencies won't be hinted so you gonna ignore them here
+- `mypy.ini` - `mypy` config, usually some of your dependencies won't be hinted so you're gonna ignore them here
 - `poetry.lock` - compiled dependencies
 - `poetry.toml` - `poetry` config, as you shouldn't enforce other devs where to put their virtual environment this is must be a separate config file
 - `pyproject.toml` - repo config
@@ -40,34 +101,6 @@ When developing a project there's a need to automate some tedious stuff that hel
 - [mypy](https://github.com/python/mypy)
 - [coverage](https://github.com/nedbat/coveragepy)
 
-## [Makefile](Makefile)
-
-To start your work, you need to set up your local environment and hooks.
-
-```sh
-make install_dev
-```
-
-You gonna put your CLI here later. It already contains calls to build tools and checks. Use `build` to run them all (`isort`, `black`, `pre_commit`, `flake8`, `mypy`, `test`).
-
-```sh
-make build
-```
-
-Please note that `build` does not encompass the coverage and dependencies updates. These need to be run separately. Coverage may not always be necessary and you're gonna be running `build` often while working locally. Updating dependencies should be approached with the utmost care, no reason to bump the versions all the time when code does the work it's intended for. Better use some automation tool like [dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file).
-
-To quickly format your repo while coding run:
-
-```sh
-make format
-```
-
-Before you commit, always run a full check. It's much more faster to run it locally, than to wait for CI build.
-
-```sh
-make build
-```
-
 ## [pre-commit](.github/hooks/.pre-commit-config.yml)
 
 This hook is here to prevent you from committing any nasty code to your repository.
@@ -80,8 +113,8 @@ This hook is here to prevent you from committing any nasty code to your reposito
 - autoformatting [black](https://github.com/psf/black)
 - finally some linter to be sure [flake8](https://gitlab.com/pycqa/flake8)
 
-Why are we using local environment to run pre-commit for us? This is rather unusual isn't it? Yes - it is. You want to use the same versions of libs (`flake8`, `black`) and have them specified in a single file. Otherwise you need to keep track of precommit dependencies as well. If you want truly separate environment for the pre-commit - use dependency groups in your package manager.
+Why are we using the local environment to run pre-commit for us? This is rather unusual, isn't it? Yes - it is. You want to use the same versions of libs (`flake8`, `black`) and have them specified in a single file. Otherwise, you need to keep track of `pre-commit` dependencies as well. If you want a truly separate environment for the `pre-commit` - use dependency groups in your package manager.
 
 ## Closing remarks
 
-Hopefully, this template helps you jump off your project. If any of these tools are unfamiliar to you, follow the links for more info on them. Feel free to customize it, this is a template after all. The point I often make while doing workshops is you being able to make your toolset. This is but an example.  Personally, I often look up how my favourite libraries are developed and take what I like. Just try not to overdo it. Don't use tools which are not necessary in your project. The main idea is to spend time actually coding, soliving problems, not thinking about code quality whatsoever.
+Hopefully, this template helps you jump off your project. If any of these tools are unfamiliar to you, follow the links for more info on them. Feel free to customize it, this is a template after all. The point I often make while doing workshops is you being able to make your toolset. This is but an example. I often look up how my favorite libraries are developed and take what I like. Just try not to overdo it. Don't use tools that are not necessary in for project. The main idea is to spend time actually coding, solving problems, and not thinking about code quality whatsoever.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-template"
-version = "0.5.0"
+version = "0.5.1"
 description = "Python template repository for ML projects"
 authors = ["peepo-dev-family"]