[skip-ci] docs: update README

Author: a-jean-andreasian

.github/logo.png

@@ -1,174 +1,128 @@
-
-<div style="text-align: center;">
-  <img src=".github/pic1.png" />
-</div>
+# <img src=".github/logo_v2.png" alt="Not Gitmodules!" height="30" /> Not Gitmodules
 
 ---
 
-# What's  `not_gitmodules`?
 
-Watch the intro:
+## Introduction
 
-[![](https://markdown-videos-api.jorgenkh.no/youtube/QkFxP_6NA84)](https://youtu.be/QkFxP_6NA84)
-
-Long story short: `not_gitmodules` is a lightweight, production-ready Python utility designed to simplify managing external modules in
-your project.
+- Not Gitmodules is a **lightweight**, **production-friendly** and **open-source** Python utility
+  designed to simplify managing external modules in
+  your project.
+- It's a replacement for Git Submodule which is: up to **10x faster**, **safer**, **simpler**, **cleaner** and the most
+  importantly - **without headaches**.
 
 ---
 
-# Why `not_gitmodules`?
-
-1. Simplicity: Minimalistic design—no unnecessary complexities.
-2. Production-Ready: Explicitly licensed for production use.
-3. Dependency-Free: Uses only Python's built-in tools.
-4. OS-Agnostic: Works seamlessly on Linux, MacOS and any other platforms where Python is available by default.
+## Effortlessness
 
---- 
+Everything you need to do is:
 
-## Important note
+1. Install Not Gitmodules. Clone this repo from GitHub or install from PyPi
+2. Create a simple YAML file.
 
-1. not_gitmodules just like Gitmodules doesn't `automatically install the dependencies`/`do not include the dependencies to your project dependency file (such as requirements.txt for Python or package.json for JavaScript)` of the submodule.
-2. not_gitmodules doesn't `download the submodules mentioned in the not_gimodules.yaml file of the submodule`.
-- Reason: it's practically inefficient, may lead to bugs and bottlenecks, and better to maintain manually.
+Not Gitmodules will handle the rest for you.
 
-How to handle?
-1. Move the containing of the dependency file to your project's dependency file and rerun the dependency installer.
-
-2.1. Important note. `not_gitmodules` keeps the view of keeping the project structure clean. All submodules amoung one project/micro-service need to go to one folder. It's recommended to use dependency injection in case of having nested not_gitmodules.
+---
 
-2.2. Move submodules to your `not_gimodules.yaml` file and rerun install accordingly.
+## Why Not Gitmodules?
 
-## Installation and Usage
+1. **Simplicity**: Minimalistic design and no unnecessary complexities.
+2. **Production-Ready**: Explicitly licensed for production use.
+3. **Dependency-Free**: Uses only Python's built-in tools.
+4. **OS-Agnostic**: Works seamlessly on Linux, MacOS and any other platforms where Python is available by default.
 
-### Installation
+---
 
-Choose one of the following methods to install `not_gitmodules`:
+## Still have questions?
 
-#### 1. Clone the repository:
+Watch the introduction video on YouTube, where Snoop Dogg will explain everything!
 
-```bash  
-git clone https://github.com/Armen-Jean-Andreasian/not_gitmodules.git
-```  
-
-#### 2. Install via pip:
-
-```bash  
-pip install not-gitmodules
-```  
+[![](https://markdown-videos-api.jorgenkh.no/youtube/QkFxP_6NA84)](https://youtu.be/QkFxP_6NA84)
 
 ---
 
-# Preparation and Usage Options
+## Usage
 
-## 1. Preparation (IMPORTANT)
 
-Create a `notgitmodules.yaml` file in your project's root directory.
 
-```yaml
-# directory_name: url (ssh or https)  
+### Part 1: Installation
 
-# Example: 
-utils:
-  file_manager: https://github.com/not-gitmodules/notgitmodules-file-manager-py
-  file_encryptor: https://github.com/not-gitmodules/notgitmodules-file-encryptor-py
+Choose the most convenient way to install Not Gitmodules:
 
-services:
-  forsaken_mail: https://github.com/malaohu/forsaken-mail
-  sim_mail: https://github.com/Webador/SlmMail
-```  
-
-## 2. Usage Options
+1. **Clone** (or download) this repository and include it to your project and use **as a part of your project's code:**
 
-You can use `not_gitmodules` in two ways:
+   ```
+   git clone [email protected]:Armen-Jean-Andreasian/not_gitmodules.git
+   ```
 
-1. **As a part of your project's code.**  
-   Just clone/download this repository and include it to your project.
-    - **Pros:** No additional dependencies or overhead.
-    - **Cons:** No CLI usage; increases the project's file size.
 
+2. **Install via a package manager** and use **as a Python package** _(example with pip)_:
 
-2. **As a Python Package (Recommended).**  
-   Install using **pip**
-
-- **Pros:** This method allows you to leverage CLI commands for better flexibility, ease with Docker, keeps the project
-  lightweight
-    - **Cons:** Additional dependency
-
-**Not recommended** option: clone/download this repository and run `pip install .`
+    ![PyPI](https://img.shields.io/pypi/v/not-gitmodules)
+    ```bash  
+    pip install not-gitmodules
+    ```  
+    - And, yeah, don't forget to add it to `requirements.txt` in advance, if you don't use Poetry.
 
 ---
 
-# Usage
-
-## A. As Part of Your Project's Code
-
-### Command:
-
-```bash  
-git clone https://github.com/Armen-Jean-Andreasian/not_gitmodules.git
-```  
-
-### Implementation:
-
-- If `notgitmodules.yaml` is located in the project root:
-
-```python
-from not_gitmodules import initializer
+### Part 2: Preparation
 
-initializer()  
-```  
-
-- If `notgitmodules.yaml` is located somewhere else. _Or has a different name._
+1. Create a YAML file in your project's root directory.
 
-```python
-from not_gitmodules import initializer
+- Tip: Naming it `notgitmodules.yaml` lets you use it without explicitly specifying it in the command.
 
-initializer('custom/path/to/config.yaml')  # Specify a custom path  
-```  
+2. Define the submodules following the pattern:
 
-  
----  
+```yaml
+folder_to_save: # Destination folder for this group of modules
+  module1: module1.url # directory_name: url (ssh or https)
+  module2: module2.url
 
-## B. As a Python Package (Recommended)
+another_folder:
+  module3: module3.url
+```
 
-This method allows you to leverage CLI commands for better flexibility.
+Example:
 
-### 1. Install the package
+```yaml
+# directory_name: url (ssh or https)  
+utils:
+  file_manager: https://github.com/not-gitmodules/notgitmodules-file-manager-py
+  file_encryptor: https://github.com/not-gitmodules/notgitmodules-file-encryptor-py
 
-```  
-pip install not_gitmodules 
+services:
+  forsaken_mail: https://github.com/malaohu/forsaken-mail
+  sim_mail: https://github.com/Webador/SlmMail
 ```  
 
----  
+The example above will download and create this structure:
 
-### 2. Add it to `requirements.txt`
-
-As this package is not used in code itself, it's easy to forget to add. So better to add in advance.
-
-#### Run:
-
-```bash  
-pip show not_gitmodules
-```  
-
-**Check the `Version` and include it to `requirements.txt` with `~=` assignment:**
+```
+utils/
+    file_manager/
+        ... (containing of the repo)
+    file_encryptor/
+        ...
 
-- Example:
-    ```text
-    not_gitmodules~=0.0
-    ```
+services:
+    forsaken_mail/
+        ...
+    sim_mail/
+        ...
+```
 
----  
+---
 
-### 3. Install the modules:
+### Part 3: Installation
 
-| Flag (all of them are optional) | Description                                                                                                                                                                                                                                      | Example                                                                                                                                |
-|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
-| `-y`, `--yaml-path`             | Specify a custom path for the `notgitmodules.yaml` configuration file. <br>By default, it looks for `notgitmodules.yaml` in the current working directory. Naming it `notgitmodules` is a matter of best practices; you can name it as you want. | • `not_gitmodules -y /path/to/custom_notgitmodules.yaml`: Uses a custom YAML file located at `/path/to/custom_notgitmodules.yaml`      |
-| `-t`, `--threaded`              | Enable threaded execution, where repositories are cloned in parallel (using threads). This flag is mutually exclusive with `-s`. <br> This is the default behavior if neither `-t` nor `-s` is specified.                                        | • `not_gitmodules -t`: Clones repositories in parallel using threads <br> • `not_gitmodules --threaded`: Same as `-t`, using long form |
-| `-s`, `--sequential`            | Enable sequential execution, where repositories are cloned one by one in the order they appear in the YAML file. This flag is mutually exclusive with `-t`.                                                                                      | • `not_gitmodules -s`: Clones repositories one by one in order <br> • `not_gitmodules --sequential`: Same as `-s`, using long form     |
+| Flag (all of them are optional)              | Description                                                                                                                                                                                                            | Example                                                                                                                                |
+|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| `-y`, `--yaml-path`                          | Specify a custom path for the YAML file. <br>By default, it looks for `notgitmodules.yaml` in the current working directory. <br>Naming it `notgitmodules` is a matter of best practices; you can name it as you want. | • `not_gitmodules -y /path/to/custom_notgitmodules.yaml`: Uses a custom YAML file located at `/path/to/custom_notgitmodules.yaml`      |
+| `-t`, `--threaded` _**(default behaviour)**_ | Enable threaded execution, where repositories are cloned in parallel (using threads). <br>This flag is mutually exclusive with `-s`. <br> This is the default behavior if neither `-t` nor `-s` is specified.          | • `not_gitmodules -t`: Clones repositories in parallel using threads <br> • `not_gitmodules --threaded`: Same as `-t`, using long form |
+| `-s`, `--sequential`                         | Enable sequential execution, where repositories are cloned one by one in the order they appear in the YAML file. This flag is mutually exclusive with `-t`.                                                            | • `not_gitmodules -s`: Clones repositories one by one in order <br> • `not_gitmodules --sequential`: Same as `-s`, using long form     |
 
-### More command examples:
+#### More command examples:
 
 - ### Default command:
 
@@ -182,75 +136,72 @@ not_gitmodules install
 - ### Command pattern:
 
 ```bash  
-not_gitmodules install --yaml-path </path/to/notgitmodules.yaml>  --threaded
+not_gitmodules install --yaml-path </path/to/notgitmodules.yaml>  --<execution_type> 
 ```  
 
 or
 
 ```bash  
-not_gitmodules install -y </path/to/notgitmodules.yaml>  -t
+not_gitmodules install -y </path/to/notgitmodules.yaml>  --sequential
 ```
 
----
-
-## Comparison
 
-Usually with undefined amount of workers in `ThereadPool` in parallel mode take more than **52%** less time than in
+> Note: Usually with undefined amount of workers in `ThereadPool` in parallel mode take more than **52%** less time than in
 parallel mode.
 
+---
 
----  
-
-### 4. Dockerizing
-
-Double-check that you:
-
-1. Created a `notgitmodules.yaml`
-2. Included `not_gitmodules` version to `requirements.txt`
-
-Then:
+### Part 4. Dockerizing
 
-3. Create your `Dockerfile`. Example:
 
 ```dockerfile  
 FROM python:3.10-slim  
 
 # Install git for not_gitmodules
 RUN apt-get update && apt-get install -y git  
-  
-WORKDIR /app  
-  
-COPY . .  
-  
+
 RUN pip install --no-cache-dir -r requirements.txt   
 
 # copy the notgitmodules.yaml file (default). Modify accordingly.
 COPY notgitmodules.yaml .
 
-# install modules using not_gitmodules
+# install modules using not_gitmodules.
 RUN not_gitmodules install -y notgitmodules.yaml -t
+
+WORKDIR /app  
   
+COPY . .
+
 CMD ["python", "main.py"]
 ```
 
 ---
 
-## Possible Issues with Private Repositories
+## Good to Know
 
-If cloning fails but you have access to the repository, provide the HTTPS repo URL instead of SSH  
-in `notgitmodules.yaml`.
+1. Not Gitmodules **doesn't require to keep the folders** with modules. You can safely .gitignore or delete them.
+2. **Do not use matching names** for the repositories in `notgitmodules.yaml` file. In that case only the first repository
+  will be downloaded and the second one will be skipped.
+3. Not Gitmodules **needs** `Git` and `PyYAML` for functioning.
+4. Not Gitmodules, just like Gitmodules, **doesn't automatically install the dependencies of submodules** _(such as requirements.txt for Python or package.json for JavaScript)_.
+5. Not Gitmodules **doesn't download the sub-dependency submodules** (if they are not defined properly for Git).
+   - Reason: it's practically inefficient, may lead to bugs and bottlenecks, and better to maintain manually.
+   - Solution: Include the sub-dependency submodule to YAML file manually.
+6. Not Gitmodules keeps the view of keeping the project structure clean. All submodules among one
+   project/microservice need to go to one folder. It's recommended to use dependency injection in case of having nested `not_gitmodules`.
+7. **Possible bottleneck** with private repositories. 
+    -  If cloning fails, but you have access to the repository, provide the HTTPS repo URL instead of SSH url in YAML file.
 
----
 
-## Worth to mention
+---
 
-- `not_gitmodules` doesn't require for you to keep the folders with modules. You can safely .gitignore/delete them.
-- Do not use matching names for the repositories in `notgitmodules.yaml` file. In that case only the first repository
-  will be downloaded and the second one - skipped.
+<div style="text-align: center;">
+  <img src=".github/pic1.png" width="300" height="300">
+</div>
 
 ---
 
-## License
+## ![License](https://img.shields.io/badge/license-Custom-blue)
 
 This project is licensed under a **Custom License**. See the [LICENSE](./LICENSE) file for full details.
 
@@ -269,3 +220,4 @@ Armen-Jean Andreasian, 2024
 <div style="text-align: center;">
   <img src=".github/pic2.png" />
 </div>
+