feat: update project template and cli

Author: colyerdeng

.gitignore

@@ -7,4 +7,5 @@
 /.zip/
 /venv/
 /dist/
-/__pycache__/
+**/__pycache__/
+*.pyc

pyproject.toml

@@ -27,6 +27,9 @@ dev = [
 [project.scripts]
 repo-scaffold = "repo_scaffold.cli:cli"
 
+[tool.setuptools.package-data]
+repo_scaffold = ["templates/**/*", "cookiecutter.json"]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

repo_scaffold/cli.py

@@ -1,64 +1,183 @@
-"""Command Line Interface module for project scaffolding.
+"""Repository scaffolding CLI tool.
 
-This module provides the CLI commands for creating new projects using cookiecutter
-templates. It serves as the main entry point for the repo_scaffold tool and handles
-all command-line interactions.
+This module provides a command-line interface for creating new projects from templates.
+It serves as the main entry point for the repo-scaffold tool.
 
-Typical usage example:
+Example:
+    To use this module as a CLI tool:
 
+    ```bash
+    # List available templates
+    $ repo-scaffold list
+
+    # Create a new project
+    $ repo-scaffold create python
+    ```
+
+    To use this module in your code:
+
+    ```python
     from repo_scaffold.cli import cli
 
     if __name__ == '__main__':
         cli()
-
-Attributes:
-    cli: The main Click command group that serves as the entry point.
+    ```
 """
 
+import json
 import os
+from pathlib import Path
+from typing import Dict, Any
+import importlib.resources
 
 import click
 from cookiecutter.main import cookiecutter
 
 
+def get_package_path(relative_path: str) -> str:
+    """Get absolute path to a resource in the package.
+    
+    Args:
+        relative_path: Path relative to the package root
+
+    Returns:
+        str: Absolute path to the resource
+    """
+    # 使用 files() 获取包资源
+    package_files = importlib.resources.files("repo_scaffold")
+    resource_path = package_files.joinpath(relative_path)
+    if not (resource_path.is_file() or resource_path.is_dir()):
+        raise FileNotFoundError(f"Resource not found: {relative_path}")
+    return str(resource_path)
+
+
+def load_templates() -> Dict[str, Any]:
+    """Load available project templates configuration.
+
+    Reads template configurations from the cookiecutter.json file in the templates directory.
+    Each template contains information about its name, path, title, and description.
+
+    Returns:
+        Dict[str, Any]: Template configuration dictionary where keys are template names
+            and values are template information:
+            {
+                "template-name": {
+                    "path": "relative/path",
+                    "title": "Template Title",
+                    "description": "Template description"
+                }
+            }
+
+    Raises:
+        FileNotFoundError: If the configuration file doesn't exist
+        json.JSONDecodeError: If the configuration file is not valid JSON
+    """
+    config_path = get_package_path("templates/cookiecutter.json")
+    with open(config_path, "r", encoding="utf-8") as f:
+        config = json.load(f)
+    return config["templates"]
+
+
 @click.group()
 def cli():
-    """Repository scaffolding CLI tool.
+    """Modern project scaffolding tool.
 
-    A tool for creating new projects from templates.
+    Provides multiple project templates for quick project initialization.
+    Use `repo-scaffold list` to view available templates,
+    or `repo-scaffold create <template>` to create a new project.
     """
-    ...
 
 
 @cli.command()
+def list():
+    """List all available project templates.
+
+    Displays the title and description of each template to help users
+    choose the appropriate template for their needs.
+    
+    Example:
+        ```bash
+        $ repo-scaffold list
+        Available templates:
+
+        python - template-python
+          Description: template for python project
+        ```
+    """
+    templates = load_templates()
+    click.echo("\nAvailable templates:")
+    for name, info in templates.items():
+        click.echo(f"\n{info['title']} - {name}")
+        click.echo(f"  Description: {info['description']}")
+
+
+@cli.command()
+@click.argument("template", required=False)
 @click.option(
-    "--template",
-    "-t",
-    default="https://github.com/ShawnDen-coder/repo-scaffold.git",
-    help="Cookiecutter template URL or path",
+    "--output-dir",
+    "-o",
+    default=".",
+    type=click.Path(file_okay=False, dir_okay=True, path_type=Path),
+    help="Directory where the project will be created",
 )
-@click.option("--output-dir", "-o", default=".", help="Where to output the generated project dir")
-@click.option("--local", "-l", is_flag=True, help="Use local template in ./template-python")
-def create(template, output_dir, local):
-    r"""Create a new project from template.
-
-    \b
-    Usage:
-        repo-scaffold create [OPTIONS]
-
-    \b
-    Examples:
-        $ repo-scaffold create
-        $ repo-scaffold create --local
-        $ repo-scaffold create -o ./my-projects
-        $ repo-scaffold create -t https://github.com/user/custom-template.git
-        $ repo-scaffold create -t ../path/to/local/template
-        $ repo-scaffold create -t gh:user/template-name
+def create(template: str, output_dir: Path):
+    """Create a new project from a template.
+
+    Creates a new project based on the specified template. If no template is specified,
+    displays a list of available templates. The project generation process is interactive
+    and will prompt for necessary configuration values.
+
+    Args:
+        template: Template name or title (e.g., 'template-python' or 'python')
+        output_dir: Target directory where the project will be created
+
+    Example:
+        Create a Python project:
+            ```bash
+            $ repo-scaffold create python
+            ```
+        
+        Specify output directory:
+            ```bash
+            $ repo-scaffold create python -o ./projects
+            ```
+        
+        View available templates:
+            ```bash
+            $ repo-scaffold list
+            ```
     """
-    if local:
-        template = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
-
-    cookiecutter(template=template, output_dir=output_dir, no_input=False)
+    templates = load_templates()
+    
+    # 如果没有指定模板，让 cookiecutter 处理模板选择
+    if not template:
+        click.echo("Please select a template to use:")
+        for name, info in templates.items():
+            click.echo(f"  {info['title']} - {name}")
+            click.echo(f"    {info['description']}")
+        return
+
+    # 查找模板配置
+    template_info = None
+    for name, info in templates.items():
+        if name == template or info["title"] == template:
+            template_info = info
+            break
+
+    if not template_info:
+        click.echo(f"Error: Template '{template}' not found")
+        click.echo("\nAvailable templates:")
+        for name, info in templates.items():
+            click.echo(f"  {info['title']} - {name}")
+        return
+
+    # 使用模板创建项目
+    template_path = get_package_path(os.path.join("templates", template_info["path"]))
+    cookiecutter(
+        template=template_path,
+        output_dir=str(output_dir),
+        no_input=False,  # 启用交互式输入，让 cookiecutter 处理所有选项
+    )
 
 
 if __name__ == "__main__":

cookiecutter.json renamed to repo_scaffold/templates/cookiecutter.json

@@ -1,7 +1,7 @@
 {
   "templates": {
     "template-python": {
-      "path": "./template-python",
+      "path": "template-python",
       "title": "python",
       "description": "template for python project"
     }

repo_scaffold/templates/template-python/cookiecutter.json

@@ -0,0 +1,28 @@
+{
+    "repo_name": "my-python-project",
+    "full_name": "Shawn Deng",
+    "email": "[email protected]",
+    "github_username": "ShawnDen-coder",
+    "project_slug": "{{ cookiecutter.repo_name.strip().lower().replace('-', '_') }}",
+    "description": "A short description of the project.",
+    "min_python_version": ["3.8", "3.9", "3.10", "3.11"],
+    "max_python_version": ["3.12"],
+    "use_mkdocs": ["yes", "no"],
+    "use_docker": ["yes", "no"],
+    "include_cli": ["yes", "no"],
+    "use_github_actions": ["yes", "no"],
+    "__prompts__": {
+        "repo_name": "项目名称 (使用 - 分隔, 例如: my-awesome-project)",
+        "full_name": "你的全名",
+        "email": "你的邮箱地址",
+        "github_username": "你的 GitHub 用户名",
+        "project_slug": "Python 包名 (用于 import)",
+        "description": "项目简短描述",
+        "min_python_version": "最低支持的 Python 版本 (这将影响测试范围和依赖兼容性)",
+        "max_python_version": "最高支持的 Python 版本",
+        "use_mkdocs": "是否使用 MkDocs 生成文档?",
+        "use_docker": "是否添加 Docker 支持?",
+        "include_cli": "是否添加命令行界面?",
+        "use_github_actions": "是否添加 GitHub Actions 支持?"
+    }
+}

template-python/hooks/__init__.py renamed to repo_scaffold/templates/template-python/hooks/__init__.py

@@ -0,0 +1,40 @@
+import os
+import shutil
+import subprocess
+
+
+def remove_cli():
+    """Remove CLI related files if not needed."""
+    cli_file = os.path.join("{{cookiecutter.project_slug}}", "cli.py")
+    if os.path.exists(cli_file):
+        os.remove(cli_file)
+
+
+def remove_github_actions():
+    """Remove GitHub Actions configuration if not needed."""
+    github_dir = os.path.join("{{cookiecutter.project_slug}}", ".github")
+    if os.path.exists(github_dir):
+        shutil.rmtree(github_dir)
+
+
+def init_project_depends():
+    """Initialize project dependencies using uv."""
+    project_dir = os.path.abspath("{{cookiecutter.project_slug}}")
+    os.chdir(project_dir)
+    
+    # 安装基础开发依赖
+    subprocess.run(["uv", "sync", "--extra", "dev"], check=True)
+    
+    # 如果启用了文档功能，安装文档依赖
+    if "{{cookiecutter.use_mkdocs}}" == "yes":
+        subprocess.run(["uv", "sync", "--extra", "docs"], check=True)
+
+
+if __name__ == "__main__":
+    if "{{cookiecutter.include_cli}}" == "no":
+        remove_cli()
+        
+    if "{{cookiecutter.use_github_actions}}" == "no":
+        remove_github_actions()
+        
+    init_project_depends()

repo_scaffold/templates/template-python/hooks/post_gen_project.py

@@ -5,11 +5,12 @@ on:
     tags:
       - '*.*.*'
 
+permissions:
+  contents: write  # 用于创建 GitHub Release
+
 jobs:
   release-build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write  # 用于创建 GitHub Release
     steps:
       - uses: actions/checkout@v4
 
@@ -32,7 +33,11 @@ jobs:
           version: ">=0.4.0"
 
       - name: Install dependencies
-        run: uv sync --extra dev
+        run: |
+          uv sync --extra dev
+          {% if cookiecutter.use_mkdocs == "yes" %}
+          uv sync --extra docs
+          {% endif %}
 
       - name: Build and test
         run: |
@@ -45,12 +50,18 @@ jobs:
           UV_PUBLISH_TOKEN: {% raw %}${{ env.PYPI_TOKEN }}{% endraw %}
         run: uv publish
 
+      {% if cookiecutter.use_mkdocs == "yes" %}
+      - name: Deploy documentation
+        run: uv run mkdocs gh-deploy --force
+        env:
+          GITHUB_TOKEN: {% raw %}${{ env.PERSONAL_ACCESS_TOKEN }}{% endraw %}
+      {% endif %}
+
       - name: Release
         uses: softprops/action-gh-release@v2
         with:
           files: |
-            dist/*.tar.gz
-            dist/*.whl
+            dist/*
           generate_release_notes: true
         env:
           GITHUB_TOKEN: {% raw %}${{ env.PERSONAL_ACCESS_TOKEN }}{% endraw %}