finalizing documentation for this branch

.gitignore

@@ -10,6 +10,12 @@ marl_venv/
 .pytest_cache/
 __pycache__/
 
+# Python cache
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+
 # Ignore compiled Python files
 *.pyc
 *.pyo

README.md

@@ -23,6 +23,18 @@ A **discrete, grid-based multi-agent predator–prey environment** designed as a
 
 ---
 
+## Documentation 
+
+Full documentation is available at: **[https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/](https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/)**
+
+- [Usage Guide](https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/usage/)
+- [Agent Concepts](https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/agents/)
+- [Environment Guide](https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/environment/)
+- [API Reference Agents](https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/api/agents/)
+- [API Reference GridWorldEnv](https://provalarous.github.io/Predator-Prey-Archetype-Gridworld-Environment/api/gridworld/)
+
+---
+
 ## Overview
 
 This repository provides a **discrete, grid-based predator-prey simulation environment** designed to support controlled, interpretable, and reproducible experiments in MARL. The environment models classic predator-prey dynamics where multiple agents (predators and prey) interact and learn in a bounded grid world.
@@ -79,6 +91,26 @@ Key goals of this framework:
 
 ## Getting Started
 
+### Repository Structure 
+
+```text
+Predator-Prey-Gridworld-Environment/
+├── src/
+│   ├── multi_agent_package/       # Core environment code
+│   │   ├── agents.py              # Agent class
+│   │   ├── gridworld.py           # GridWorldEnv class
+│   │   └── __init__.py
+│   └── baselines/                 # RL algorithm implementations
+│       ├── IQL/                   # Independent Q-Learning
+│       ├── CQL/                   # Central Q-Learning
+│       └── MIXED/                 # Mixed strategies
+├── docs/                          # Documentation (MkDocs)
+├── tests/                         # Unit tests
+├── requirements.txt               # Runtime dependencies
+├── requirements-dev.txt           # Development dependencies
+└── mkdocs.yml                     # Documentation config
+```
+
 ### Installation
 
 Clone the repository:
@@ -100,24 +132,35 @@ pip install -r requirements.txt
 from multi_agent_package.gridworld import GridWorldEnv
 from multi_agent_package.agents import Agent
 
-# Define agents
-agent1 = Agent("prey", "Tom")
-agent2 = Agent("predator", "Jerry")
+# Define agents (type, team, name)
+predator = Agent("predator", "predator_1", "Hunter")
+prey = Agent("prey", "prey_1", "Runner")
 
 # Create environment
-env = GridWorldEnv(agents=[agent1, agent2], render=True)
+env = GridWorldEnv(
+    agents=[predator, prey],
+    size=8,
+    render_mode="human"
+)
 
 # Run a single episode
-obs = env.reset()
+obs, info = env.reset(seed=42)
 done = False
+
 while not done:
-    actions = env.sample_random_actions()
-    obs, rewards, done, info = env.step(actions)
-    env.render()
+    actions = {
+        "Hunter": env.action_space.sample(),
+        "Runner": env.action_space.sample()
+    }
+    result = env.step(actions)
+    done = result["done"]
+
+env.close()
 ```
 
 ---
 
+
 ## Contributing
 
 We welcome contributions that improve the clarity, utility, or extensibility of the environment. If you have ideas for enhancements, fixes, or new features, please open an issue or submit a pull request.

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+m.ahmedatif720@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/contributing.md

@@ -1,25 +1,153 @@
-# Contributing
+# Contributing to Predator-Prey Gridworld Environment
 
-## How to Contribute
+Thank you for your interest in contributing! This project aims to provide a clean, interpretable environment for Multi-Agent Reinforcement Learning research, and contributions from the community help make that possible.
 
-1. **Fork** the repository
-2. **Branch**: `fix/short-desc` or `feat/short-desc`
-3. **Test**: Run `pytest`
-4. **Style**: Follow code style guidelines
-5. **PR**: Open a pull request and link related issues
+We welcome contributions of all kinds: bug fixes, new features, documentation improvements, and more. This guide will walk you through the process step-by-step.
 
 ---
 
-## Development Setup
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+
+---
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please treat all contributors with respect and help us maintain a welcoming community.
+
+---
+
+## Getting Started
+
+### 1. Fork the Repository
+
+Click the **"Fork"** button on the top right of the repository page to create your own copy.
+
+### 2. Clone Your Fork
 
 ```bash
-# Clone your fork
 git clone https://github.com/YOUR_USERNAME/Predator-Prey-Gridworld-Environment.git
 cd Predator-Prey-Gridworld-Environment
+```
 
-# Install dev dependencies
+### 3. Add Upstream Remote
+```bash
+git remote add upstream https://github.com/ProValarous/Predator-Prey-Gridworld-Environment.git
+```
+
+### 4. Set Up Development Environment
+```bash 
+# Create virtual environment
+python -m venv venv
+
+# Activate it (Windows)
+.\venv\Scripts\Activate.ps1
+
+# Activate it (macOS/Linux)
+source venv/bin/activate
+
+# Install development dependencies
 pip install -r requirements-dev.txt
 
+# Install the package in editable mode
+pip install -e .
+
 # Install pre-commit hooks
 pre-commit install
+```
+
+### 5. Verify Setup 
+```bash
+# Run tests
+pytest tests/ -v # not implemented yet
+
+# Check formatting
+black --check src/
+
+# Check linting
+flake8 src/
+```
+
+## Development Workflow
+
+### Step 1: Sync with Upstream
+Before starting any work, ensure your fork is up to date
+
+### Step 2: Create Feature/Fix Branch
+Never work directly on `main`. Always create a new branch:
+```bash 
+git checkout -b feat/short-desc
+```
+or 
+```bash 
+git checkout -b fix/short-desc
+```
+
+### Step 3: Make Your Changes
+Edit the code, add tests, update documentation as needed.
+
+### Step 4: Format and Lint
+Before committing, ensure your code meets our standards:
+```bash
+# Format code with Black
+black src/
+
+# Check for linting errors
+flake8 src/
+
+# Run tests
+pytest tests/ -v
+```
+
+### Step 5: Commit Your Changes 
+```bash 
+git add .
+git commit -m "feat: Add your feature description"
+```
+
+### Step 6: Push to your fork
+```bash
+git push -u origin feat/short-desc
+```
+
+### Step 7: Open a Pull Request
+
+1. Go to the original repository on GitHub
+2. Click "Compare & pull request"
+3. Fill in the PR template with a clear description
+4. Link any related issues
+5. Submit the PR
+
+
+## Quick Reference 
+```bash 
+# Complete workflow in one place
+
+# 1. Setup (one-time)
+git clone https://github.com/YOUR_USERNAME/Predator-Prey-Gridworld-Environment.git
+cd Predator-Prey-Gridworld-Environment
+git remote add upstream https://github.com/ProValarous/Predator-Prey-Gridworld-Environment.git
+pip install -r requirements-dev.txt
+pip install -e .
+pre-commit install
+
+# 2. Start new feature
+git checkout main
+git pull upstream main
+git checkout -b feat/my-feature
+
+# 3. Make changes, then format and test
+black src/
+flake8 src/
+pytest tests/ -v
+
+# 4. Commit and push
+git add .
+git commit -m "feat: Add my feature"
+git push -u origin feat/my-feature
+
+# 5. Open PR on GitHub
 ```