Changes in README, CONTRIBUTING.md and docs

Author: danibcorr

CONTRIBUTING.md

@@ -1,127 +1,131 @@
 # Contributing to Python Project Template
 
-Hello and welcome! We're excited that you're interested in contributing to the Python
-Project Template project.
+Thank you for your interest in contributing to the **Python Project Template**.
+Contributions of all types are welcome, including code, documentation, bug reports, and
+feature requests. This guide outlines the recommended workflow for contributing
+effectively.
 
-We appreciate all types of contributions whether it's code, documentation, bug reports,
-or feature requests.
+## Joining the Project
 
-## Want to Join the Team?
+If you are interested in contributing or collaborating more closely, feel free to reach
+out to the maintainers.
 
-If you’re interested in contributing or collaborating more closely, feel free to reach
-out!.
+## Ways to Contribute
 
-## How to Contribute Code
+You can contribute by:
 
-There are two main ways to contribute:
+- Reporting bugs or requesting new features.
+- Submitting code contributions, including bug fixes, improvements, or new features.
 
-- Request a **new feature** or report a **bug**
-- Submit a **code contribution** (bug fix, feature, improvement, etc.)
+> Note: While we strive to respond promptly, we cannot guarantee an immediate reply due
+> to the number of projects we maintain.
 
-> Please note: we're actively supporting several projects, so while we’ll do our best to
-> respond promptly, we can't always guarantee an immediate reply.
+## Contributing Code
 
 ### Step 1: Open an Issue
 
-Start by opening an issue to describe your proposal or the problem you've found. This
-helps us evaluate and guide the work before coding begins.
+Start by opening an issue to describe your proposed change or the problem you
+encountered. This helps maintainers review and guide the work before coding begins.
 
-> If your change is small (e.g., a typo fix or minor bug), feel free to skip this and
-> open a pull request directly.
+> For minor changes, such as typo fixes, you may skip this step and submit a pull
+> request directly.
 
 ### Step 2: Make Your Changes
 
-1. Fork this repository.
-2. Clone it locally.
-3. Create a new branch for your change.
+1. Fork the repository.
+2. Clone your fork locally.
+3. Create a new branch for your changes.
 4. Set up your development environment (see [Setup Environment](#setup-environment)).
-5. Make your changes and ensure all tests pass.
+5. Implement your changes and ensure all tests pass.
 
 ### Step 3: Submit a Pull Request
 
-Once your changes are ready, open a pull request (PR) from your forked branch to the
-`main` branch.
+Open a pull request (PR) from your branch to the `main` branch of the repository.
 
 ### Step 4: Code Review
 
-A maintainer will review your PR and may leave feedback. You may be asked to revise the
-code, improve formatting, or adjust test coverage.
+A maintainer will review your PR and may provide feedback. You might be asked to:
 
-> Fix any failing tests and address review comments before re-requesting review.
+- Revise code for correctness or clarity
+- Adjust formatting
+- Improve test coverage
+
+> Address any review comments and ensure all tests pass before requesting a re-review.
 
 ### Step 5: Merge
 
-Once approved, a maintainer will merge the pull request.
+After approval, a maintainer will merge your pull request.
 
 ## Setup Environment
 
-You can set up your dev environment in two ways:
+You can set up the development environment in one of two ways:
 
 ### Option 1: Dev Container
 
-We support Visual Studio Code, GitHub Codespaces, and JetBrains IDEs dev containers for
-an easy, preconfigured development setup.
+We support development containers for Visual Studio Code, GitHub Codespaces, and
+JetBrains IDEs. This provides a preconfigured environment for immediate work.
 
 ### Option 2: Local Setup
 
-To work locally:
+To set up locally:
 
-1. Install `git`, `python`, and preferably [`uv`](https://github.com/astral-sh/uv).
-2. Clone the repository.
-3. Run:
+1. Ensure `git` and Python (3.10, 3.11, or 3.12) are installed.
+2. Optionally, install [`uv`](https://github.com/astral-sh/uv) to manage dependency
+   groups.
+3. Clone the repository and run:
 
-   ```bash
-   make install
-   ```
+```bash
+make install
+```
 
-> The required Python version is defined in `pyproject.toml`. If using `uv`, it will
-> create a compatible virtual environment automatically.
+> If using `uv`, a compatible virtual environment will be created automatically.
 
 ## Running Tests
 
-We use [pytest](https://docs.pytest.org/) for testing. Run all tests with:
+All tests are run using [pytest](https://docs.pytest.org/):
 
 ```bash
 make tests
 ```
 
 ## Code Formatting & Quality Checks
 
-We use `make` to automate formatting, linting, and checks. Just run:
+Use `make` to automate formatting, linting, static analysis, testing, and documentation:
 
 ```bash
 make
 ```
 
-This will:
+This executes:
 
-- Install dependencies
-- Run linters (`black`, `isort`, `ruff`, ...)
-- Run static analysis (`complexipy`)
-- Run tests
-- Serve the documentation locally
+- Dependency installation
+- Linters (`ruff`, `black`, `isort`)
+- Static analysis (`complexipy`, `mypy`, `bandit`)
+- Test suite execution
+- Local documentation preview
 
-## Docstring Style
+## Docstring Guidelines
 
-A good function docstring typically includes:
+Function docstrings should include:
 
-- A short one-line description
-- Optional longer explanation
-- `Args:` section with parameter descriptions
+- A concise one-line description
+- Optional detailed explanation
+- `Args:` section describing parameters
 - `Returns:` section
-- Optional `Raises:` section
-- Optional `Examples:` section
+- Optional `Raises:` section for exceptions
+- Optional `Examples:` section demonstrating usage
 
-Please write clear, concise, and consistent docstrings.
+Maintain clarity, consistency, and completeness in docstrings.
 
 ## Other Ways to Contribute
 
-Not a fan of writing code? You can still help by:
+Non-code contributions are highly valuable, including:
 
 - Improving documentation or examples
-- Fixing typos or grammar
-- Suggesting features or usability improvements
-- Helping triage and respond to issues
+- Fixing typos and grammar issues
+- Suggesting features or enhancements
+- Assisting with issue triage and responses
 
-Thank you for being part of Python Project Template's journey. We’re thrilled to have
-you here. If you have questions, feel free to reach out or open an issue.
+Thank you for contributing to the Python Project Template. Your participation helps
+improve the project for everyone. If you have questions, feel free to reach out or open
+an issue.

README.md

@@ -4,65 +4,92 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/danibcorr/python-project-template/actions/workflows/workflow.yml"><img src="https://github.com/danibcorr/python-project-template/actions/workflows/workflow.yml/badge.svg"></a>
+  <a href="https://github.com/danibcorr/python-project-template/actions/workflows/workflow.yml">
+    <img src="https://github.com/danibcorr/python-project-template/actions/workflows/workflow.yml/badge.svg">
+  </a>
   <img src="https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue">
   <a href="https://github.com/danibcorr/python-project-template/blob/main/LICENSE" target="_blank">
-      <img src="https://img.shields.io/github/license/danibcorr/python-project-template" alt="License">
+    <img src="https://img.shields.io/github/license/danibcorr/python-project-template" alt="License">
   </a>
 </p>
 
 # 🐍 Python Project Template
 
-Welcome to the Python Project Template — your go-to starter kit for building robust
-Python projects with clean code, strong testing, built-in security, and automated
-deployment. Whether you're launching a new idea or refining your workflow, this template
-sets you up for success.
+Python Project Template provides a ready-to-use structure for Python projects,
+integrating best practices for code quality, testing, security, documentation, and
+CI/CD. It helps developers start new projects quickly with a maintainable and
+professional foundation.
+
+## Features
+
+- **Linting & Type Checking**: Ruff and Mypy for clean, consistent code.
+- **Security Scanning**: Bandit detects potential vulnerabilities.
+- **Code Complexity Analysis**: Complexipy identifies complex functions and modules.
+- **Testing Suite**: Reliable unit testing with Pytest.
+- **Auto Documentation**: MkDocs + GitHub Pages for automated docs.
+- **CI/CD**: GitHub Actions automates linting, testing, and documentation deployment.
+
+## GitHub Actions
 
-## What's Inside
+The template includes a preconfigured GitHub Actions workflow that runs automatically on
+pushes or pull requests. The workflow performs the following steps:
 
-- **Linting & Type Checking**: Keep your code clean with
-  [Ruff](https://docs.astral.sh/ruff/) and [Mypy](http://mypy-lang.org/).
-- **Security Scanning**: Catch vulnerabilities early using
-  [Bandit](https://bandit.readthedocs.io/en/latest/).
-- **Code Complexity Analysis**: Understand your codebase with
-  [Complexipy](https://rohaquinlop.github.io/complexipy/).
-- **Testing Suite**: Reliable testing with [Pytest](https://docs.pytest.org/en/stable/).
-- **Auto Documentation**: Generate and deploy docs with
-  [MkDocs](https://www.mkdocs.org/) + [GitHub Pages](https://pages.github.com/).
-- **CI/CD**: Automate your workflow using GitHub Actions — from linting and testing to
-  doc deployment.
+1. Checks out the repository and sets up Python.
+2. Installs project dependencies.
+3. Runs linters, type checks, security scans, and complexity analysis.
+4. Executes tests with Pytest.
+5. Optionally generates and deploys documentation.
 
-And more.
+This ensures every change is validated, tested, and documented automatically,
+maintaining high-quality and reproducible results.
 
 ## Getting Started
 
+Before starting, ensure that you have required Python installed and a virtual
+environment set up. It is recommended to create an isolated environment (e.g., using
+`venv`) to manage dependencies cleanly. Additionally, ensure that
+[`uv`](https://github.com/astral-sh/uv) is installed in your environment to handle
+grouped dependency installations.
+
 ### 1. Generate Your Project
 
-Activate your Python environment, install `cookiecutter`, and run:
+Use Cookiecutter to create a new project from the template:
 
 ```bash
 cookiecutter https://github.com/danibcorr/python-project-template.git
 ```
 
+Follow the prompts to configure project metadata, package name, and other options.
+
 ### 2. Install Dependencies
 
-Use the included `Makefile`:
+Activate your virtual environment and install all dependencies using the included
+`Makefile`:
 
 ```bash
 make install
 ```
 
+This installs development, testing, and documentation tools as defined in
+`pyproject.toml`.
+
 ### 3. Run the Pipeline
 
-Lint, test, and check your project:
+Execute the quality pipeline, which includes linting, type checking, security analysis,
+complexity checks, and test execution:
 
 ```bash
 make pipeline
 ```
 
-Or run the full suite including docs:
+### 4. Run the Full Workflow (Optional)
+
+To perform a complete setup including dependency installation, full quality checks, and
+local documentation preview:
 
 ```bash
 make all
 ```
 
+This ensures that the project environment is fully prepared for development and
+validation.