Update README and add comments

README.md

@@ -1,17 +1,25 @@
+![Python Logo](https://www.python.org/static/community_logos/python-logo-master-v3-TM.png)
+
 [![CI](https://github.com/jzombie/pipper/workflows/CI/badge.svg)](https://github.com/jzombie/pipper/actions/workflows/ci.yml)
 [![ShellCheck](https://github.com/jzombie/pipper/workflows/ShellCheck/badge.svg)](https://github.com/jzombie/pipper/actions/workflows/shellcheck.yml)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/b83c0ce7f8924db99be96d045ffc4503)](https://app.codacy.com/gh/jzombie/pipper/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 
 # Pipper - Python Virtual Environment Manager
 
-Pipper intends to make working with pip and virtual environments a bit easier.
+Pipper intends to make working with pip and virtual environments a bit easier by wrapping some of the most common functionality in dependency-less Bash.
 
 Pipper automates setting up virtual environments and automatically runs them for you.
 
 Pipper is not intended to replace pip, and is intended to be used alongside pip.  If you're not using pip as your package manager, it is not recommended to use this project.
 
 Pipper: **P**ackage **I**nstaller and **P**ython **P**roject **E**nvironment **R**unner
 
+## Why Not Use Poetry?
+
+Pipper simplifies working with pip and virtual environments in Python, particularly beneficial for those who prefer pip's standardized approach, especially when forking and modifying projects with `requirements.txt` files. While Poetry offers its advantages, Pipper sticks to pip's workflow for seamless integration with these files.
+
+With Pipper, you can continue to use pip, because Pipper uses pip itself.
+
 ## Commands/Features
 
 Note: All commands can be run from *outside* of the virtual environment and will automatically launch as needed.

pipper.sh

@@ -7,6 +7,8 @@ VENV_NAME="venv"
 
 # Function to create a virtual environment.
 # Accepts an optional Python interpreter version as an argument.
+# Usage: create_venv [python-version]
+# Example: create_venv python3.8
 create_venv() {
     local PYTHON
     # If a specific Python interpreter is provided, use it.
@@ -43,6 +45,8 @@ create_venv() {
 }
 
 # Function to launch a sub-shell with the virtual environment activated.
+# Usage: launch_venv_shell
+# Example: launch_venv_shell
 launch_venv_shell() {
     if [ -d "$VENV_NAME" ]; then
         echo "Launching a sub-shell with the virtual environment activated..."
@@ -63,10 +67,10 @@ launch_venv_shell() {
     fi
 }
 
-
-
 # Function to activate the virtual environment.
 # Accepts a boolean argument to decide whether to activate it immediately.
+# Usage: activate_venv [true|false]
+# Example: activate_venv true
 activate_venv() {
     local activate="$1"
     if [ "$activate" = true ]; then
@@ -94,6 +98,8 @@ activate_venv() {
 }
 
 # Function to install Python dependencies from a requirements file.
+# Usage: install_requirements
+# Example: install_requirements
 install_requirements() {
     if [ -f "requirements.txt" ]; then
         activate_venv true
@@ -105,13 +111,17 @@ install_requirements() {
 }
 
 # Function to freeze current Python dependencies into a requirements file.
+# Usage: freeze_requirements
+# Example: freeze_requirements
 freeze_requirements() {
     activate_venv true
     pip freeze > requirements.txt
     echo "Requirements frozen into requirements.txt."
 }
 
 # Function to uninstall Python dependencies listed in a requirements file.
+# Usage: uninstall_requirements
+# Example: uninstall_requirements
 uninstall_requirements() {
     if [ -f "requirements.txt" ]; then
         activate_venv true
@@ -123,6 +133,9 @@ uninstall_requirements() {
 }
 
 # Function to run a specified Python script within the virtual environment.
+# Accepts the path to a Python script as an argument.
+# Usage: run_script [script-path]
+# Example: run_script my_file.py
 run_script() {
     if [ -f "$1" ]; then
         activate_venv true
@@ -134,6 +147,9 @@ run_script() {
 }
 
 # Function to generate a command for running tests in dry-run mode.
+# Accepts optional arguments for the source directory and pattern.
+# Usage: run_tests_dry_run [source-dir] [pattern]
+# Example: run_tests_dry_run test test*.py
 run_tests_dry_run() {
     local source_dir="${1:-test}"
     local pattern="${2:-test*.py}"
@@ -144,6 +160,9 @@ run_tests_dry_run() {
 }
 
 # Function to execute unit tests within the virtual environment.
+# Accepts optional arguments for the source directory, pattern, and echo flag.
+# Usage: run_tests [source-dir] [pattern] [--echo]
+# Example: run_tests test test*.py --echo
 run_tests() {
     local source_dir="${1:-test}"
     local pattern="${2:-test*.py}"