diff --git a/README.md b/README.md index 182d36a8d905..9b147a88baaa 100644 --- a/README.md +++ b/README.md @@ -50,3 +50,6 @@ We are on [Discord](https://the-algorithms.com/discord) and [Gitter](https://git ## πŸ“œ List of Algorithms See our [directory](DIRECTORY.md) for easier navigation and a better overview of the project. + +For understanding the whole process of contribution refer to [usage-example](Usage-example.md). +Highly useful for beginners. \ No newline at end of file diff --git a/Usage-example.md b/Usage-example.md new file mode 100644 index 000000000000..ef5d4138b9fa --- /dev/null +++ b/Usage-example.md @@ -0,0 +1,91 @@ +🧩**Usage Example** + +This repository contains implementations of many popular algorithms and data structures in Python. +You can clone the repository, explore, run tests, and even add your own algorithms easily. + +πŸ› οΈ**Clone the Repository** +# Clone the repo +git clone https://github.com/TheAlgorithms/Python.git + +# Move into the folder +cd Python + +πŸ§ͺ**Run Tests** +You can use the built-in Python test framework to verify that all algorithms work correctly. +# Run all tests +python -m unittest discover + +# Or run a specific test file +python -m unittest tests/test_sorting.py + +πŸ’‘ Tip: Always make sure your Python version matches the one mentioned in the repository’s requirements (usually Python 3.10+). + +🧠**Try Out an Algorithm** +You can run any algorithm file directly to understand how it works. +For example, let’s run the Bubble Sort algorithm: + +# Navigate to the sorting folder +cd sorting + +# Run bubble_sort.py +python bubble_sort.py + +Output Example: +Unsorted array: [5, 1, 4, 2, 8] +Sorted array: [1, 2, 4, 5, 8] + +✍️ Add Your Own Algorithm +You can contribute by adding new algorithms or improving existing ones. +1.Fork the repository +2.Create a new branch for your feature(#most important thing to do) + +# ----> git checkout -b add-new-algorithm <---- + +3.Add your code inside the appropriate directory (e.g. graphs/, sorting/, etc.) +4.Include: +Proper function docstrings + +5.Example usage +1.Time and space complexity comments +2.Test your code and submit a Pull Request πŸš€ + +🧹**Example Folder Structure** + +Python/ +β”‚ +β”œβ”€β”€ data_structures/ +β”‚ └── stacks/ +β”‚ └── stack_using_list.py +β”‚ +β”œβ”€β”€ graphs/ +β”‚ └── dijkstra.py +β”‚ +β”œβ”€β”€ sorting/ +β”‚ └── bubble_sort.py +β”‚ +└── tests/ + └── test_sorting.py + +πŸ“¦**Example Output (from Dijkstra’s Algorithm)** +# python graphs/dijkstra.py +Sample Output +# Shortest distances from source: +A: 0 +B: 4 +C: 2 +D: 7 + +🧾 **Commit and Create a Pull Request** +Once you’ve verified everything works: + +# git add . +# git commit -m "Added new algorithm: My Algorithm" +# git push origin add-new-algorithm + +# Then, open your fork on GitHub and click β€œ**Compare & pull request**”. +Be sure to: +1.Write a clear PR title and description +2.Explain what your code does and where it fits +3.Add example input/output and complexity if possible + +