From 63de429d2c0c58d2aa6bd419a04932c0738a2095 Mon Sep 17 00:00:00 2001 From: devvratpathak Date: Tue, 7 Oct 2025 23:06:53 +0530 Subject: [PATCH 1/2] docs: enhance README with table of contents, installation guide, and features section - Add comprehensive table of contents for easy navigation - Include detailed installation steps with virtual environment setup - Add usage examples showing how to run and import algorithms - Create features section listing all algorithm categories - Add explicit license section with MIT License information - Expand contributing section with quick start guide - Add about section explaining repository purpose Fixes #13111 --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 127 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 182d36a8d905..9413e0e8de32 100644 --- a/README.md +++ b/README.md @@ -39,14 +39,140 @@ Implementations are for learning purposes only. They may be less efficient than the implementations in the Python standard library. Use them at your discretion. +## ๏ฟฝ Table of Contents + +- [About](#-about) +- [Features](#-features) +- [Getting Started](#-getting-started) + - [Installation](#installation) + - [Usage](#usage) +- [Algorithm Categories](#-algorithm-categories) +- [Community Channels](#-community-channels) +- [Contributing](#-contributing) +- [License](#-license) +- [List of Algorithms](#-list-of-algorithms) + +## ๏ฟฝ About + +This repository contains Python implementations of various algorithms and data structures for educational purposes. Whether you're a student learning algorithms, a developer preparing for technical interviews, or someone interested in computer science fundamentals, this collection provides clear and well-documented examples. + +## โœจ Features + +This repository includes implementations of algorithms across multiple categories: + +- **Sorting Algorithms**: Bubble sort, Quick sort, Merge sort, Heap sort, and more +- **Searching Algorithms**: Binary search, Linear search, Jump search, Interpolation search +- **Data Structures**: Linked lists, Stacks, Queues, Trees, Graphs, Hash tables +- **Graph Algorithms**: BFS, DFS, Dijkstra's algorithm, Floyd-Warshall, Bellman-Ford +- **Dynamic Programming**: Knapsack, Longest Common Subsequence, Edit Distance +- **Machine Learning**: Neural networks, Linear regression, K-means clustering +- **Mathematical Algorithms**: Prime number algorithms, GCD, LCM, Number theory +- **String Algorithms**: Pattern matching, String manipulation, Parsing +- **Cryptography**: Various cipher implementations +- **Computer Vision**: Image processing algorithms +- **And many more!** + +All implementations include: +- Clear documentation and explanations +- Type hints for better code readability +- Doctests for validation +- Educational comments + ## ๐Ÿš€ Getting Started -๐Ÿ“‹ Read through our [Contribution Guidelines](CONTRIBUTING.md) before you contribute. +### Installation + +1. **Clone the repository** + ```bash + git clone https://github.com/TheAlgorithms/Python.git + cd Python + ``` + +2. **Set up a virtual environment (recommended)** + ```bash + python -m venv venv + + # On Windows + venv\Scripts\activate + + # On macOS/Linux + source venv/bin/activate + ``` + +3. **Install dependencies** + ```bash + pip install -r requirements.txt + ``` + +### Usage + +Each algorithm is self-contained in its own file. You can run any algorithm directly or import it into your own projects. + +**Example 1: Running an algorithm directly** +```bash +python sorts/quick_sort.py +``` + +**Example 2: Importing and using an algorithm** +```python +from sorts.quick_sort import quick_sort + +# Sort a list +numbers = [64, 34, 25, 12, 22, 11, 90] +sorted_numbers = quick_sort(numbers) +print(sorted_numbers) # Output: [11, 12, 22, 25, 34, 64, 90] +``` + +**Example 3: Running doctests** +```bash +python -m doctest -v sorts/bubble_sort.py +``` + +## ๐Ÿ“‚ Algorithm Categories + +For a complete list of all implemented algorithms organized by category, see our [DIRECTORY.md](DIRECTORY.md) file. ## ๐ŸŒ Community Channels We are on [Discord](https://the-algorithms.com/discord) and [Gitter](https://gitter.im/TheAlgorithms/community)! Community channels are a great way for you to ask questions and get help. Please join us! +## ๐Ÿค Contributing + +We welcome contributions from the community! Before contributing: + +1. ๐Ÿ“‹ Read through our [Contribution Guidelines](CONTRIBUTING.md) +2. ๐Ÿ” Check existing implementations to avoid duplicates +3. โœ… Ensure your code follows our coding standards +4. ๐Ÿงช Include doctests and proper documentation +5. ๐ŸŽฏ Make sure all tests pass before submitting + +**Quick Start for Contributors:** +```bash +# Install pre-commit hooks +pip install pre-commit +pre-commit install + +# Run tests +python -m pytest + +# Format code +pip install ruff +ruff check +``` + +Contributions that are most welcome: +- New algorithm implementations +- Improvements to existing algorithms +- Better documentation and explanations +- Bug fixes +- Test coverage improvements + +## ๐Ÿ“„ License + +This project is licensed under the [MIT License](LICENSE.md) - see the [LICENSE.md](LICENSE.md) file for details. + +This means you are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software. + ## ๐Ÿ“œ List of Algorithms See our [directory](DIRECTORY.md) for easier navigation and a better overview of the project. From 96aa436e6e3e2004fa8b969239b4ce1b8590883e Mon Sep 17 00:00:00 2001 From: devvratpathak Date: Wed, 8 Oct 2025 01:42:37 +0530 Subject: [PATCH 2/2] docs: enhance README with table of contents, installation guide, and features section - Add comprehensive table of contents for easy navigation - Include detailed installation steps with virtual environment setup - Add usage examples showing how to run and import algorithms - Create features section listing all algorithm categories - Add explicit license section with MIT License information - Expand contributing section with quick start guide - Add about section explaining repository purpose Fixes #13111 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9413e0e8de32..4b07b2279e86 100644 --- a/README.md +++ b/README.md @@ -91,10 +91,10 @@ All implementations include: 2. **Set up a virtual environment (recommended)** ```bash python -m venv venv - + # On Windows venv\Scripts\activate - + # On macOS/Linux source venv/bin/activate ```