docs: add documentation for this organization

Author: monok8i

.gitignore

@@ -0,0 +1,4 @@
+# uv
+
+uv.lock
+

.python-version

@@ -0,0 +1 @@
+3.12

docs/index.md

@@ -0,0 +1,148 @@
+# Python Boilerplate
+
+A collection of modern Python project templates with pre-configured development tools, CI/CD pipelines, and best practices.
+
+---
+
+## Overview
+
+**Python Boilerplate** is a curated collection of project templates designed to help developers quickly bootstrap new Python projects with industry best practices and modern tooling already configured.
+
+!!! tip "✨ Why Use These Templates?"
+    - **⚡ Fast Setup** - Get a production-ready project structure in seconds
+    - **🛠️ Modern Tooling** - Pre-configured linters, formatters, type checkers, and testing frameworks
+    - **🚀 CI/CD Ready** - Automated workflows for GitHub Actions
+    - **🐳 Docker Support** - Development and production containerization
+    - **📚 Documentation** - MkDocs integration with Material theme
+    - **🔧 Developer Experience** - Pre-commit hooks, Makefile automation, and dev containers
+
+---
+
+## Available Templates
+
+### 🚀 UV Template
+
+Modern Python project template using [uv](https://github.com/astral-sh/uv) - the ultra-fast Python package manager.
+
+!!! info "Repository & Documentation"
+    **[📂 uv-template](https://github.com/python-boilerplate/uv-template)** | **[📖 Documentation](https://python-boilerplate.github.io/uv-template/)**
+
+!!! example "🎯 Core Features"
+    - 🐍 **Python 3.10+** - Modern Python version support
+    - ⚡ **uv** - Ultra-fast Python project manager with dependency installer and lock file support
+    - 🐳 **Docker Support** - Multi-stage Dockerfiles for easy local development and clean production containers
+    - 🔄 **GitHub Actions CI/CD** - Automated linting, testing, static analysis, and security checks for every branch
+    - 💻 **Dev Containers** - Ready-to-use development environment in GitHub Codespaces or VSCode Remote Containers
+
+!!! example "🛠️ Code Quality Tools"
+    - 🔍 **Ruff** - Built-in linting and formatting
+    - 🔎 **MyPy** - Static type checking
+    - 🧪 **Pytest** - Testing framework with async support
+    - 📊 **Vermin** - Minimum Python version analysis
+
+!!! example "⚙️ Developer Experience"
+    - 🎣 **Pre-commit Hooks** - Runs linters, formatting, and tests automatically before every commit
+    - 📝 **Commitizen** - Standardized commit messages with automated versioning and changelog updates
+    - 🌍 **Environment Management** - Stage-based environment variable configuration for dev/prod with switching via `APP_STAGE`
+    - 📖 **MkDocs Documentation** - Project documentation generated with MkDocs and the Material theme
+    - 🔧 **Makefile Automation** - Common tasks available as simple Makefile commands
+
+---
+
+### 📦 Poetry Template
+
+Classic Python project template using [Poetry](https://python-poetry.org/) for dependency management.
+
+!!! info "Repository & Documentation"
+    **[📂 poetry-template](https://github.com/python-boilerplate/poetry-template)** | **[📖 Documentation](https://python-boilerplate.github.io/poetry-template/)**
+
+!!! example "🎯 Core Features"
+    - 🐍 **Python 3.10+** - Modern Python version support
+    - 📦 **Poetry** - Mature dependency management with lock files
+    - 🐳 **Docker Support** - Containerization for development and production
+    - 🔄 **CI/CD Pipelines** - Automated quality checks and deployment workflows
+    - 📚 **Structured Documentation** - Well-organized project documentation
+
+!!! example "🛠️ Code Quality Tools"
+    - 🔍 **Ruff** - Built-in linting and formatting
+    - 🔎 **MyPy** - Static type checking
+    - 🧪 **Pytest** - Testing framework with async support
+    - 📊 **Vermin** - Minimum Python version analysis
+
+!!! example "⚙️ Developer Experience"
+    - 🎣 **Pre-commit Hooks** - Runs linters, formatting, and tests automatically before every commit
+    - 📝 **Commitizen** - Standardized commit messages with automated versioning and changelog updates
+    - 🌍 **Environment Management** - Stage-based environment variable configuration for dev/prod with switching via `APP_STAGE`
+    - 📖 **MkDocs Documentation** - Project documentation generated with MkDocs and the Material theme
+    - 🔧 **Makefile Automation** - Common tasks available as simple Makefile commands
+
+
+---
+
+## Quick Start
+
+!!! tip "Getting Started"
+    1. **Choose your template** from the list above
+    2. **Use as GitHub Template** - Click "Use this template" button on the repository page
+    3. **Clone your new repository**
+       ```bash
+       git clone https://github.com/your-username/your-project-name.git
+       cd your-project-name
+       ```
+    4. **Initialize the project**
+       ```bash
+       make init
+       ```
+    5. **Start developing!** 🎉
+
+---
+
+## Templates Comparison
+
+| Feature | UV Template | Poetry Template |
+|---------|-------------|-----------------|
+| Package Manager | uv (ultra-fast) | Poetry (mature) |
+| Dependency Locking | ✅ uv.lock | ✅ poetry.lock |
+| Python Version Management | ✅ Built-in | ❌ External tool needed |
+| Speed | ⚡ Fastest | 🐌 Slower |
+| Ecosystem Maturity | 🆕 New but growing | 🏆 Well-established |
+| Learning Curve | 📈 Minimal | 📊 Moderate |
+
+---
+
+## Useful Links
+
+!!! info "Documentation & Resources"
+    - **[GitHub Organization](https://github.com/python-boilerplate)** - All templates and repositories
+    - **[UV Template Docs](https://python-boilerplate.github.io/uv-template/)** - Complete uv template documentation
+    - **[Poetry Template Docs](https://python-boilerplate.github.io/poetry-template/)** - Complete poetry template documentation
+
+---
+
+## Contributing
+
+!!! question "Want to Contribute?"
+    We welcome contributions! If you have ideas for improvements or new templates:
+
+    1. **Open an issue** to discuss your idea
+    2. **Fork the repository** and make your changes
+    3. **Submit a pull request** with a clear description
+
+---
+
+## Support
+
+!!! help "Need Help?"
+    - 📋 **Issues** - Report bugs or request features in the specific template repository
+    - 💬 **Discussions** - Ask questions in GitHub Discussions
+    - 📧 **Contact** - Reach out to [@monok8i](https://github.com/monok8i)
+
+---
+
+!!! note "License"
+    All templates are released under the [MIT License](https://github.com/python-boilerplate/uv-template/blob/main/LICENSE).
+
+---
+
+!!! success "Made with ❤️ by [@monok8i](https://github.com/monok8i)"
+    [⭐ Follow the Organization](https://github.com/python-boilerplate) • [📋 Browse Templates](https://github.com/orgs/python-boilerplate/repositories) • [💬 Join Discussions](https://github.com/orgs/python-boilerplate/discussions)

docs/poetry-template/features/ci/github_actions.md

@@ -0,0 +1,82 @@
+# GitHub Actions
+
+A powerful CI/CD platform built into GitHub for automating workflows: testing, linting, type-checking, and more.
+
+---
+
+## What is it used for here?
+!!! question "!"
+    - **Automatically runs linters, tests, and checks code quality for every push and pull request**
+    - **Ensures your code works on multiple Python versions**
+    - **Checks code compatibility with the minimum Python version using Vermin**
+    - **Runs all key quality tools: Ruff, MyPy, Pytest, and more**
+
+---
+
+## How does it work in this template?
+
+- **Workflow files are located in [`.github/workflows/`](https://github.com/python-boilerplate/uv-template/tree/main/.github/workflows)**.
+- Actions are triggered automatically on push or pull request to key branches.
+- Each workflow installs only used dependencies using default `pip`.
+- Main scenarios covered:
+    - **Linting:** Checks code style with [Ruff](../code_quality/ruff.md)
+    - **Type Checking:** Validates type annotations using [MyPy](../code_quality/mypy.md)
+    - **Testing:** Runs all tests with [Pytest](../code_quality/pytest.md)
+    - **Compatibility:** Checks minimal Python version compatibility with [Vermin](../code_quality/vermin.md)
+    - **Multi-Python:** Runs tests on several Python versions (e.g., 3.10, 3.11, 3.12, 3.13)
+
+---
+
+## Example workflows
+
+!!! example "Common workflow: Lint, Typecheck, Test"
+    ```yaml title=".github/workflows/code-quality.yml"
+    name: Lint, Typecheck, Test
+
+    on:
+      push:
+        branches: [main]
+      pull_request:
+        branches: [main]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        strategy:
+          matrix:
+            python-version: ["3.10", "3.11", "3.12"]
+        steps:
+          - uses: actions/checkout@v4
+          - uses: actions/setup-python@v4
+            with:
+              python-version: ${{ matrix.python-version }}
+          - name: Install dependencies
+            run: uv pip install -r requirements-dev.txt
+          - name: Lint
+            run: uv run ruff check ./src/
+          - name: Typecheck
+            run: uv run mypy ./src/
+          - name: Test
+            run: uv run pytest -v
+    ```
+
+!!! example "Compatibility check: Vermin"
+    See [Vermin section](../code_quality/vermin.md) for details.
+
+---
+
+## How to add or edit workflows
+
+- **All workflow YAML files are in `.github/workflows/`**
+- To add a new workflow, just copy an existing `.yml` file and edit as needed.
+
+---
+
+## Configuration and secrets
+
+- No sensitive secrets are used by default in this template.
+- For advanced scenarios (e.g., publishing, deploying), add secrets in GitHub repo settings and reference via `${{ secrets.YOUR_SECRET }}`.
+
+---
+
+For more details, see the [GitHub Actions Documentation](https://docs.github.com/en/actions).

docs/poetry-template/features/ci/gitlab_ci.md

@@ -0,0 +1,78 @@
+# MyPy
+
+Static type checker for Python, designed to ensure code correctness and catch type errors before runtime.
+
+---
+
+## What is it used for here?
+!!! question "!"
+    - **`type checking` Python code to catch type errors early**
+    - **enforcing and verifying type annotations**
+    - **checking code quality before every commit and during CI pipelines**
+
+---
+
+## How to use it?
+
+- **In this case, the Makefile does the same as running the commands directly via uv. The Makefile is only needed to shorten commands.**
+
+!!! tip "!"
+
+    === "Makefile"
+
+        ```bash
+        make typecheck
+        ```
+
+    === "Manually (Without make and uv)"
+
+        ```bash
+        mypy --config-file=pyproject.toml ./src/
+        ```
+
+    === "Manually (With uv)"
+
+        ```bash
+        uv run mypy --config-file=pyproject.toml ./src/
+        ```
+
+## How to use it with pre-commit?
+
+To use MyPy with pre-commit, you need to add the appropriate configuration to `.pre-commit-config.yaml`.
+
+!!! tip "!"
+
+    === "Hook (by mypy)"
+
+        ```yaml title=".pre-commit-config.yaml"
+        - repo: https://github.com/pre-commit/mirrors-mypy
+          rev: v1.16.0
+          hooks:
+            - id: mypy
+              args: [ --config-file=pyproject.toml ]
+              files: ^src/
+        ```
+
+    === "Hook (your own)"
+
+        ```yaml title=".pre-commit-config.yaml"
+        - repo: local
+          hooks:
+            # check types
+            - id: mypy
+              name: Mypy
+              description: Run Mypy for type checking types in Python code
+              entry: uv run mypy
+              types: [python]
+              language: system
+              always_run: true
+              pass_filenames: false
+              args: [ --config-file=pyproject.toml, ./src/ ]
+        ```
+
+## Configuration
+All configuration for Mypy in this template is located in [pyproject.toml](https://github.com/python-boilerplate/uv-template/blob/main/pyproject.toml) under the `[tool.mypy]` section.
+
+---
+
+For more details on configuration, see the [MyPy Documentation](https://mypy.readthedocs.io/en/stable/)

docs/poetry-template/features/code_quality/mypy.md

@@ -0,0 +1,78 @@
+# Pytest
+
+A powerful framework for testing Python code, supporting both synchronous and asynchronous tests.
+
+---
+
+## What is it used for here?
+!!! question "!"
+    - **`unit testing` and `integration testing` of Python code**
+    - **testing both synchronous and asynchronous functions**
+    - **automated quality checks before every commit and in CI pipelines**
+
+---
+
+## Important
+
+!!! warning "!"
+    - For testing asynchronous functions, the [pytest-asyncio](https://pytest-asyncio.readthedocs.io/en/latest/) extension is added, which makes it easy to write and run async tests alongside regular ones.
+
+---
+
+## How to use it?
+
+- **In this case, the Makefile does the same as running the commands directly via uv. The Makefile is only needed to shorten commands.**
+
+!!! tip "!"
+
+    === "Makefile"
+
+        ```bash
+        make test
+        ```
+
+    === "Manually (Without make and uv)"
+
+        ```bash
+        pytest -v
+        ```
+
+    === "Manually (With uv)"
+
+        ```bash
+        uv run pytest -v
+        ```
+
+## How to use it with pre-commit?
+
+Only a local hook is used for integration with pre-commit.
+!!! question "Why?"
+    Pytest does not officially provide a pre-commit hook repository, and running tests often requires custom parameters or environments (for example, via uv or with specific options). A local hook gives maximum flexibility and control.
+
+!!! tip "!"
+
+    === "Local hook (recommended)"
+
+        ```yaml title=".pre-commit-config.yaml"
+        - repo: local
+          hooks:
+            # Run pytest.
+            - id: pytest
+              name: pytest
+              entry: uv run pytest
+              language: system
+              types: [python]
+              pass_filenames: false
+              args: [ -v ]
+        ```
+---
+
+## Configuration
+
+All configuration for Pytest (such as plugins) in this template is located in [pyproject.toml](https://github.com/python-boilerplate/uv-template/blob/main/pyproject.toml) under the `[tool.pytest.ini_options]` section.
+
+---
+
+For more details on configuration, see the [Pytest Documentation](https://docs.pytest.org/en/stable/)
+
+About async tests: [pytest-asyncio documentation](https://pytest-asyncio.readthedocs.io/en/stable/)