feat: add cookiecutter template for interactive package generation

README.md

@@ -18,7 +18,43 @@
 
 ## Get Started
 
-1. Use this template repository to create your own project repository by clicking the "Use this template" button on GitHub or visiting [MPPT](https://github.com/shenxiangzhuang/mppt).
+### Option 1: Using Cookiecutter (Recommended)
+
+The easiest way to use this template is with cookiecutter, which will interactively prompt you for all the necessary information:
+
+1. Install cookiecutter:
+   ```bash
+   pip install cookiecutter
+   # or
+   uv tool install cookiecutter
+   ```
+
+2. Generate your project:
+   ```bash
+   cookiecutter https://github.com/shenxiangzhuang/mppt.git
+   ```
+
+3. Answer the prompts to customize your project:
+   - Project name
+   - Author information
+   - GitHub username
+   - Package description
+   - Python versions to support
+   - Optional features (docs, pre-commit, GitHub Actions, etc.)
+
+4. Navigate to your new project and set up the development environment:
+   ```bash
+   cd your-project-name
+   uv venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   uv sync --all-extras --dev
+   ```
+
+### Option 2: Using GitHub Template
+
+Alternatively, you can use this as a GitHub template:
+
+1. Click the "Use this template" button on GitHub or visit [MPPT](https://github.com/shenxiangzhuang/mppt).
 
 2. Replace all instances of MPPT, shenxiangzhuang, and other template-specific details with your own information:
    - Project name, author, and GitHub username in all files

cookiecutter.json

@@ -0,0 +1,33 @@
+{
+    "package_name": "my_python_package",
+    "project_short_description": "A modern Python package",
+    "author_name": "Your Name",
+    "author_email": "[email protected]",
+    "github_username": "yourusername",
+    "version": "0.1.0",
+    "python_min_version": ["3.9", "3.10", "3.11", "3.12", "3.13"],
+    "python_max_version": ["3.9", "3.10", "3.11", "3.12", "3.13"],
+    "license": ["MIT", "Apache-2.0", "BSD-3-Clause", "GPL-3.0", "LGPL-2.1"],
+    "include_docs": ["y", "n"],
+    "include_pre_commit": ["y", "n"],
+    "include_github_actions": ["y", "n"],
+    "include_codecov": ["y", "n"],
+    "development_status": [
+        "1 - Planning",
+        "2 - Pre-Alpha",
+        "3 - Alpha",
+        "4 - Beta",
+        "5 - Production/Stable",
+        "6 - Mature",
+        "7 - Inactive"
+    ],
+    "command_line_interface": ["Click", "Argparse", "None"],
+    "_copy_without_render": [
+        "*.svg",
+        "*.png",
+        "*.jpg",
+        "*.jpeg",
+        "*.gif",
+        "docs/overrides/main.html"
+    ]
+}

hooks/post_gen_project.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Post-generation hook for cookiecutter template."""
+
+import os
+import shutil
+import re
+
+
+def remove_file_or_dir(file_path):
+    """Remove file or directory if it exists."""
+    if os.path.exists(file_path):
+        if os.path.isdir(file_path):
+            shutil.rmtree(file_path)
+        else:
+            os.remove(file_path)
+
+
+def generate_python_versions(min_version, max_version):
+    """Generate list of Python versions between min and max (inclusive)."""
+    # Extract major and minor versions
+    min_parts = min_version.split(".")
+    max_parts = max_version.split(".")
+
+    min_major, min_minor = int(min_parts[0]), int(min_parts[1])
+    max_major, max_minor = int(max_parts[0]), int(max_parts[1])
+
+    versions = []
+
+    # For now, assume all versions are 3.x
+    if min_major == 3 and max_major == 3:
+        for minor in range(min_minor, max_minor + 1):
+            versions.append(f"3.{minor}")
+
+    return versions
+
+
+def update_pyproject_toml():
+    """Update pyproject.toml with correct Python version configuration."""
+    min_version = "{{ cookiecutter.python_min_version }}"
+    max_version = "{{ cookiecutter.python_max_version }}"
+
+    # Generate the list of supported Python versions
+    python_versions = generate_python_versions(min_version, max_version)
+
+    # Read the current pyproject.toml
+    with open("pyproject.toml", "r") as f:
+        content = f.read()
+
+    # Generate classifiers
+    classifiers = []
+    for version in python_versions:
+        classifiers.append(f'    "Programming Language :: Python :: {version}",')
+
+    # Replace the Python version classifiers placeholder
+    replacement = "\n".join(classifiers)
+    content = content.replace("    # PYTHON_VERSION_CLASSIFIERS_PLACEHOLDER", replacement)
+
+    # Write back the updated content
+    with open("pyproject.toml", "w") as f:
+        f.write(content)
+
+
+def main():
+    """Remove files/directories based on configuration and fix Python versions."""
+
+    # Update Python version configuration
+    update_pyproject_toml()
+
+    # Remove docs if not included
+    if "{{ cookiecutter.include_docs }}" == "n":
+        remove_file_or_dir("docs")
+        remove_file_or_dir("mkdocs.yml")
+
+    # Remove pre-commit config if not included
+    if "{{ cookiecutter.include_pre_commit }}" == "n":
+        remove_file_or_dir(".pre-commit-config.yaml")
+
+    # Remove GitHub Actions if not included
+    if "{{ cookiecutter.include_github_actions }}" == "n":
+        remove_file_or_dir(".github")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -31,6 +31,7 @@ dev = [
     "pytest-cov",
     "pytest-sugar",
     "hypothesis>=6.112.0",
+    "cookiecutter",
 ]
 docs = [
     "mkdocs",

{{cookiecutter.package_name}}/.github/workflows/build_docs.yaml

@@ -0,0 +1,58 @@
+name: Build Docs
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.9"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Install dependencies
+      run: |
+        uv sync --extra docs --dev
+
+    - name: Build documentation
+      run: |
+        uv run mkdocs build --strict
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main'
+    needs: build-docs
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.9"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Install dependencies
+      run: |
+        uv sync --extra docs --dev
+
+    - name: Deploy documentation
+      run: |
+        uv run mkdocs gh-deploy --force

{{cookiecutter.package_name}}/.github/workflows/test.yaml

@@ -0,0 +1,44 @@
+name: Test
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${% raw %}{{ matrix.python-version }}{% endraw %}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${% raw %}{{ matrix.python-version }}{% endraw %}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Install dependencies
+      run: |
+        uv sync --all-extras --dev
+
+    - name: Run tests
+      run: |
+        uv run pytest --cov={{ cookiecutter.package_name }} --cov-report=xml
+    {%- if cookiecutter.include_codecov == "y" %}
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+    {%- endif %}

{{cookiecutter.package_name}}/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]

{{cookiecutter.package_name}}/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.7.0] - 2025-04-25
+
+### Added
+
+* add(test): add mutmut pkg by @shenxiangzhuang in [#164](https://github.com/shenxiangzhuang/mppt/pull/164)
+* add(doc): sphinx-immaterial theme by @shenxiangzhuang in [#165](https://github.com/shenxiangzhuang/mppt/pull/165)
+
+### Changed
+
+* chore(linting): update Ruff lint configuration by @shenxiangzhuang in [#157](https://github.com/shenxiangzhuang/mppt/pull/157)
+* pkg: remove lock file by @shenxiangzhuang in [#158](https://github.com/shenxiangzhuang/mppt/pull/158)
+* chore: remove dev container by @shenxiangzhuang in [#161](https://github.com/shenxiangzhuang/mppt/pull/161)
+
+### CI/CD
+
+* ci: uv cache prune by @shenxiangzhuang in [#150](https://github.com/shenxiangzhuang/mppt/pull/150)
+* ci(publish): use pypi trusted publisher by @shenxiangzhuang in [#162](https://github.com/shenxiangzhuang/mppt/pull/162)
+
+## [0.6.0] - 2025-03-06
+
+### Added
+
+- CI: add mypy and ruff in test workflow
+
+### Changed
+
+- Linter & formatter: use ruff only, remove isort, black, flake8
+
+## [0.5.0] - 2025-01-03
+
+### Changed
+
+- Use uv to manage the package rather than poetry (#106)
+- Drop the support for Python 3.8 (#110)
+
+## [0.4.0] - 2024-06-11
+
+### Added
+
+- Poetry: Add commitizen, a conventional commit tool (#71)
+- Add `py.typed` file to support type hinting (#70)
+- Add sql linter: SQLFluff (#58)
+- Add task runner just (#50)
+- Add package management tool uv (#49)
+- Add Locust as a load testing tool (#39)
+
+## [0.3.0] - 2023-12-14
+
+### Added
+
+- Add ruff as extra linter and formatter: both in dependency and pre-commit (#31)
+- Add more details about the linters and formatters with the resource from Google SRE book
+- Add doctest (#34)
+
+## [0.2.0] - 2023-12-01
+
+### Added
+
+- Documentations for all the features (#20)
+- Quick sort implementation for hypothesis testing (#22)
+
+### Changed
+
+- Change package management from Rye to Poetry (#15, #19)
+
+### Removed
+
+- Sweep AI App
+
+## [0.1.1] - 2023-08-15
+
+### Changed
+
+- reorg this package template
+
+## [0.1.0] - 2023-08-15
+
+### Added
+
+- add this package template