Skip to content

Commit 63de429

Browse files
committed
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
1 parent 9372040 commit 63de429

File tree

1 file changed

+127
-1
lines changed

1 file changed

+127
-1
lines changed

README.md

Lines changed: 127 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,140 @@
3939

4040
Implementations are for learning purposes only. They may be less efficient than the implementations in the Python standard library. Use them at your discretion.
4141

42+
## � Table of Contents
43+
44+
- [About](#-about)
45+
- [Features](#-features)
46+
- [Getting Started](#-getting-started)
47+
- [Installation](#installation)
48+
- [Usage](#usage)
49+
- [Algorithm Categories](#-algorithm-categories)
50+
- [Community Channels](#-community-channels)
51+
- [Contributing](#-contributing)
52+
- [License](#-license)
53+
- [List of Algorithms](#-list-of-algorithms)
54+
55+
## � About
56+
57+
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.
58+
59+
## ✨ Features
60+
61+
This repository includes implementations of algorithms across multiple categories:
62+
63+
- **Sorting Algorithms**: Bubble sort, Quick sort, Merge sort, Heap sort, and more
64+
- **Searching Algorithms**: Binary search, Linear search, Jump search, Interpolation search
65+
- **Data Structures**: Linked lists, Stacks, Queues, Trees, Graphs, Hash tables
66+
- **Graph Algorithms**: BFS, DFS, Dijkstra's algorithm, Floyd-Warshall, Bellman-Ford
67+
- **Dynamic Programming**: Knapsack, Longest Common Subsequence, Edit Distance
68+
- **Machine Learning**: Neural networks, Linear regression, K-means clustering
69+
- **Mathematical Algorithms**: Prime number algorithms, GCD, LCM, Number theory
70+
- **String Algorithms**: Pattern matching, String manipulation, Parsing
71+
- **Cryptography**: Various cipher implementations
72+
- **Computer Vision**: Image processing algorithms
73+
- **And many more!**
74+
75+
All implementations include:
76+
- Clear documentation and explanations
77+
- Type hints for better code readability
78+
- Doctests for validation
79+
- Educational comments
80+
4281
## 🚀 Getting Started
4382

44-
📋 Read through our [Contribution Guidelines](CONTRIBUTING.md) before you contribute.
83+
### Installation
84+
85+
1. **Clone the repository**
86+
```bash
87+
git clone https://github.com/TheAlgorithms/Python.git
88+
cd Python
89+
```
90+
91+
2. **Set up a virtual environment (recommended)**
92+
```bash
93+
python -m venv venv
94+
95+
# On Windows
96+
venv\Scripts\activate
97+
98+
# On macOS/Linux
99+
source venv/bin/activate
100+
```
101+
102+
3. **Install dependencies**
103+
```bash
104+
pip install -r requirements.txt
105+
```
106+
107+
### Usage
108+
109+
Each algorithm is self-contained in its own file. You can run any algorithm directly or import it into your own projects.
110+
111+
**Example 1: Running an algorithm directly**
112+
```bash
113+
python sorts/quick_sort.py
114+
```
115+
116+
**Example 2: Importing and using an algorithm**
117+
```python
118+
from sorts.quick_sort import quick_sort
119+
120+
# Sort a list
121+
numbers = [64, 34, 25, 12, 22, 11, 90]
122+
sorted_numbers = quick_sort(numbers)
123+
print(sorted_numbers) # Output: [11, 12, 22, 25, 34, 64, 90]
124+
```
125+
126+
**Example 3: Running doctests**
127+
```bash
128+
python -m doctest -v sorts/bubble_sort.py
129+
```
130+
131+
## 📂 Algorithm Categories
132+
133+
For a complete list of all implemented algorithms organized by category, see our [DIRECTORY.md](DIRECTORY.md) file.
45134

46135
## 🌐 Community Channels
47136

48137
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!
49138

139+
## 🤝 Contributing
140+
141+
We welcome contributions from the community! Before contributing:
142+
143+
1. 📋 Read through our [Contribution Guidelines](CONTRIBUTING.md)
144+
2. 🔍 Check existing implementations to avoid duplicates
145+
3. ✅ Ensure your code follows our coding standards
146+
4. 🧪 Include doctests and proper documentation
147+
5. 🎯 Make sure all tests pass before submitting
148+
149+
**Quick Start for Contributors:**
150+
```bash
151+
# Install pre-commit hooks
152+
pip install pre-commit
153+
pre-commit install
154+
155+
# Run tests
156+
python -m pytest
157+
158+
# Format code
159+
pip install ruff
160+
ruff check
161+
```
162+
163+
Contributions that are most welcome:
164+
- New algorithm implementations
165+
- Improvements to existing algorithms
166+
- Better documentation and explanations
167+
- Bug fixes
168+
- Test coverage improvements
169+
170+
## 📄 License
171+
172+
This project is licensed under the [MIT License](LICENSE.md) - see the [LICENSE.md](LICENSE.md) file for details.
173+
174+
This means you are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software.
175+
50176
## 📜 List of Algorithms
51177

52178
See our [directory](DIRECTORY.md) for easier navigation and a better overview of the project.

0 commit comments

Comments
 (0)