sdk-bsp-rzn2l-etherkit/docs/source/setup_new_project.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
新项目快速设置脚本
帮助用户快速配置新的SDK文档项目
"""

import os
import sys
import shutil
import yaml
from pathlib import Path

def get_user_input(prompt, default=""):
    """获取用户输入"""
    if default:
        user_input = input(f"{prompt} (默认: {default}): ").strip()
        return user_input if user_input else default
    else:
        return input(f"{prompt}: ").strip()

def create_config_interactive():
    """交互式创建配置文件"""
    print("=" * 60)
    print("SDK 文档项目快速设置")
    print("=" * 60)
    
    # 项目基本信息
    print("\n📋 项目基本信息:")
    project_name = get_user_input("SDK文档名称", "My_SDK_Docs")
    project_title = get_user_input("SDK文档标题", "My SDK 文档")
    project_description = get_user_input("SDK描述", f"{project_title} 提供了丰富的示例项目，包括基础功能、驱动示例和组件示例。")
    project_version = get_user_input("版本号", "0.0.1")
    project_author = get_user_input("作者", "your_name")
    project_copyright = get_user_input("版权信息", "2025, your_company")
    
    # 仓库信息
    print("\n📦 仓库信息:")
    repo_name = get_user_input("GitHub仓库名称", "your-sdk-repo")
    
    # 项目命名模式
    print("\n🔧 项目命名模式:")
    print("请根据你的项目命名规则设置模式匹配")
    sdk_prefix = get_user_input("SDK项目前缀", "my_sdk")
    
    # 构建配置
    config = {
        'project': {
            'name': project_name,
            'title': project_title,
            'description': project_description,
            'version': project_version,
            'author': project_author,
            'copyright': project_copyright,
            'language': 'zh_CN'
        },
        'repository': {
            'name': repo_name,
            'projects_dir': '../projects',
            'docs_dir': '.'
        },
        'categories': {
            'basic': {
                'name': '基础篇',
                'description': '基础功能示例',
                'patterns': [
                    f'{sdk_prefix}_basic_*',
                    f'{sdk_prefix}_blink_led',
                    f'{sdk_prefix}_factory'
                ]
            },
            'driver': {
                'name': '驱动篇',
                'description': '外设驱动示例',
                'patterns': [
                    f'{sdk_prefix}_driver_*',
                    f'{sdk_prefix}_usb_*'
                ]
            },
            'component': {
                'name': '组件篇',
                'description': '网络组件示例',
                'patterns': [
                    f'{sdk_prefix}_component_*'
                ]
            },
            'protocol': {
                'name': '工业协议篇',
                'description': '工业协议示例',
                'patterns': [
                    f'{sdk_prefix}_ethercat_*',
                    f'{sdk_prefix}_modbus_*',
                    f'{sdk_prefix}_profinet_*',
                    f'{sdk_prefix}_ethernetip_*',
                    f'{sdk_prefix}_ethernet'
                ]
            }
        },
        'generation': {
            'copy_files': [
                'README.md',
                'README_zh.md'
            ],
            'copy_dirs': [
                'figures'
            ],
            'output_structure': [
                'basic',
                'driver',
                'component',
                'protocol'
            ]
        },
        'sphinx': {
            'theme': 'sphinx_rtd_theme',
            'extensions': [
                'myst_parser'
            ],
            'source_suffix': {
                '.rst': 'restructuredtext',
                '.md': 'markdown'
            },
            'myst_extensions': [
                'colon_fence',
                'deflist',
                'dollarmath',
                'html_image',
                'html_admonition',
                'replacements',
                'smartquotes',
                'strikethrough',
                'substitution',
                'tasklist'
            ]
        }
    }
    
    return config

def save_config(config, output_path="config.yaml"):
    """保存配置文件"""
    with open(output_path, 'w', encoding='utf-8') as f:
        yaml.dump(config, f, default_flow_style=False, allow_unicode=True, indent=2)
    print(f"✓ 配置文件已保存: {output_path}")

def create_github_workflow(repo_name):
    """创建GitHub Actions工作流"""
    workflow_content = f"""name: Deploy Sphinx docs to GitHub Pages

on:
  push:
    branches:
      - master
      - main

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write
      id-token: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          
      - name: Set up environment
        run: |
          export LANG=C.UTF-8
          export LC_ALL=C.UTF-8
          
      - name: Configure Git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"

      - name: Cache pip dependencies
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{{{ runner.os }}}}-pip-${{{{ hashFiles('source/requirements.txt') }}}}
          restore-keys: |
            ${{{{ runner.os }}}}-pip-

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r source/requirements.txt

      - name: Generate documentation
        run: |
          cd source
          python version_generator.py
          
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{{{ secrets.GITHUB_TOKEN }}}}
          publish_dir: source/_build/html
          force_orphan: true
          user_name: 'github-actions[bot]'
          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
"""
    
    workflow_dir = Path("../.github/workflows")
    workflow_dir.mkdir(parents=True, exist_ok=True)
    
    workflow_path = workflow_dir / "gh-pages.yml"
    with open(workflow_path, 'w', encoding='utf-8') as f:
        f.write(workflow_content)
    
    print(f"✓ GitHub Actions工作流已创建: {workflow_path}")

def create_readthedocs_config():
    """创建Read the Docs配置文件"""
    rtd_config = """# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
  
# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
   configuration: source/conf.py

# Optional but recommended, declare the Python requirements required
# to build your documentation
python:
    install:
      - requirements: source/requirements.txt
"""
    
    rtd_path = Path("../.readthedocs.yaml")
    with open(rtd_path, 'w', encoding='utf-8') as f:
        f.write(rtd_config)
    
    print(f"✓ Read the Docs配置文件已创建: {rtd_path}")

def create_versions_list():
    """创建版本列表文件"""
    versions_content = """# 版本列表
# 每行一个版本，以#开头的行为注释
# 支持以下格式:
# - master (最新版本)
# - v1.0 (具体版本)
# - v1.1
# - v2.0

master
v1.0
"""
    
    versions_dir = Path("../.github")
    versions_dir.mkdir(parents=True, exist_ok=True)
    
    versions_path = versions_dir / "versions.list"
    with open(versions_path, 'w', encoding='utf-8') as f:
        f.write(versions_content)
    
    print(f"✓ 版本列表文件已创建: {versions_path}")

def main():
    """主函数"""
    print("🚀 SDK文档项目快速设置工具")
    print("此工具将帮助您快速配置新的SDK文档项目")
    
    # 检查是否在正确的目录
    if not Path("doc_generator.py").exists():
        print("❌ 错误: 请在source目录中运行此脚本")
        sys.exit(1)
    
    # 交互式创建配置
    config = create_config_interactive()
    
    # 保存配置文件
    save_config(config)
    
    # 创建GitHub相关文件
    repo_name = config['repository']['name']
    create_github_workflow(repo_name)
    create_readthedocs_config()
    create_versions_list()
    
    print("\n" + "=" * 60)
    print("✅ 项目设置完成!")
    print("=" * 60)
    print("\n📝 下一步操作:")
    print("1. 检查并修改 config.yaml 文件")
    print("2. 确保项目目录结构正确")
    print("3. 运行测试构建:")
    print("   python build_local.py --check")
    print("4. 构建文档:")
    print("   python build_local.py")
    print("5. 本地预览:")
    print("   python build_local.py --serve")
    print("\n🔗 部署相关:")
    print("- GitHub Pages: 推送到master分支自动部署")
    print("- Read the Docs: 连接仓库后自动构建")
    print("\n📚 更多信息请查看 README.md")

if __name__ == "__main__":
    main()