sdk-bsp-rzn2l-etherkit/docs/source/utils/i18n_config.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
国际化配置管理器
处理中英文文档的配置、目录结构和内容生成
"""

import os
import re
import yaml
from pathlib import Path
from typing import Dict, List, Optional, Tuple, Any
from dataclasses import dataclass


@dataclass
class CategoryConfig:
    """分类配置"""
    name: str
    name_en: str
    description: str
    patterns: List[str]


@dataclass
class ProjectConfig:
    """项目配置"""
    name: str
    title: str
    description: str
    description_en: str
    version: str
    author: str
    copyright: str
    website: str


@dataclass
class I18nConfig:
    """国际化配置"""
    project: ProjectConfig
    categories: Dict[str, CategoryConfig]
    repository: Dict[str, Any]
    generation: Dict[str, Any]
    sphinx: Dict[str, Any]


class I18nConfigManager:
    """国际化配置管理器"""
    
    def __init__(self, config_path: Path):
        self.config_path = config_path
        self.config = self._load_config()
    
    def _load_config(self) -> I18nConfig:
        """加载配置文件"""
        with open(self.config_path, 'r', encoding='utf-8') as f:
            data = yaml.safe_load(f) or {}
        
        # 解析项目配置
        project_data = data.get('project', {})
        project = ProjectConfig(
            name=project_data.get('name', ''),
            title=project_data.get('title', ''),
            description=project_data.get('description', ''),
            description_en=project_data.get('description_en', ''),
            version=project_data.get('version', ''),
            author=project_data.get('author', ''),
            copyright=project_data.get('copyright', ''),
            website=project_data.get('website', '')
        )
        
        # 解析分类配置
        categories = {}
        for key, cat_data in data.get('categories', {}).items():
            categories[key] = CategoryConfig(
                name=cat_data.get('name', ''),
                name_en=cat_data.get('name_en', ''),
                description=cat_data.get('description', ''),
                patterns=cat_data.get('patterns', [])
            )
        
        return I18nConfig(
            project=project,
            categories=categories,
            repository=data.get('repository', {}),
            generation=data.get('generation', {}),
            sphinx=data.get('sphinx', {})
        )
    
    def get_category_name(self, category_key: str, language: str = 'zh') -> str:
        """获取分类名称"""
        if category_key not in self.config.categories:
            return category_key
        
        category = self.config.categories[category_key]
        if language == 'en':
            return category.name_en or category.name
        return category.name
    
    def get_project_config(self, language: str = 'zh') -> Dict[str, str]:
        """获取项目配置"""
        project = self.config.project
        if language == 'en':
            return {
                'name': project.name,
                'title': f"{project.name} Documentation",
                'description': project.description_en or project.description,
                'version': project.version,
                'author': project.author,
                'copyright': project.copyright,
                'website': project.website,
                'language': 'en'
            }
        else:
            return {
                'name': project.name,
                'title': project.title,
                'description': project.description,
                'version': project.version,
                'author': project.author,
                'copyright': project.copyright,
                'website': project.website,
                'language': 'zh_CN'
            }
    
    def get_sphinx_config(self, language: str = 'zh') -> Dict[str, Any]:
        """获取Sphinx配置"""
        base_config = self.config.sphinx.copy()
        
        if language == 'en':
            base_config.update({
                'language': 'en',
                'html_lang': 'en',
                'html_title': f"{self.config.project.name} Documentation",
                'html_short_title': self.config.project.name,
                'html_search_language': 'en',
                'html_search_options': {
                    'dict': 'en'
                }
            })
        else:
            base_config.update({
                'language': 'zh_CN',
                'html_lang': 'zh-CN',
                'html_title': self.config.project.title,
                'html_short_title': self.config.project.title,
                'html_search_language': 'zh',
                'html_search_options': {
                    'dict': 'zh'
                }
            })
        
        return base_config
    
    def get_toc_structure(self, language: str = 'zh') -> List[Dict[str, Any]]:
        """获取目录结构"""
        structure = []
        
        for category_key in self.config.generation.get('output_structure', []):
            if category_key in self.config.categories:
                category = self.config.categories[category_key]
                structure.append({
                    'key': category_key,
                    'name': self.get_category_name(category_key, language),
                    'description': category.description,
                    'patterns': category.patterns
                })
        
        return structure
    
    def get_file_suffix(self, language: str = 'zh') -> str:
        """获取文件后缀"""
        return '_zh' if language == 'zh' else ''
    
    def get_index_filename(self, language: str = 'zh') -> str:
        """获取索引文件名"""
        return f"index{self.get_file_suffix(language)}.rst"
    
    def get_html_filename(self, base_name: str, language: str = 'zh') -> str:
        """获取HTML文件名"""
        if language == 'zh':
            return f"{base_name}_zh.html"
        return f"{base_name}.html"
    
    def get_markdown_filename(self, base_name: str, language: str = 'zh') -> str:
        """获取Markdown文件名"""
        if language == 'zh':
            return f"{base_name}_zh.md"
        return f"{base_name}.md"
    
    def extract_headings_from_markdown(self, file_path: Path) -> List[Dict[str, Any]]:
        """从Markdown文件中提取标题结构"""
        headings = []
        
        if not file_path.exists():
            return headings
        
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        
        # 匹配标题的正则表达式
        heading_pattern = r'^(#{1,6})\s+(.+)$'
        
        for line_num, line in enumerate(content.split('\n'), 1):
            match = re.match(heading_pattern, line.strip())
            if match:
                level = len(match.group(1))
                title = match.group(2).strip()
                
                # 生成锚点ID
                anchor_id = self._generate_anchor_id(title)
                
                headings.append({
                    'level': level,
                    'title': title,
                    'anchor_id': anchor_id,
                    'line_num': line_num
                })
        
        return headings
    
    def _generate_anchor_id(self, title: str) -> str:
        """生成锚点ID"""
        # 移除特殊字符，转换为小写，用连字符连接
        anchor_id = re.sub(r'[^\w\s-]', '', title.lower())
        anchor_id = re.sub(r'[-\s]+', '-', anchor_id)
        return anchor_id.strip('-')
    
    def generate_toc_content(self, category_key: str, language: str = 'zh') -> str:
        """生成目录内容"""
        category = self.config.categories.get(category_key)
        if not category:
            return ""
        
        category_name = self.get_category_name(category_key, language)
        
        # 查找该分类下的所有项目
        projects = []
        docs_dir = self.config_path.parent
        
        for pattern in category.patterns:
            # 在docs目录下查找匹配的项目
            for item in docs_dir.glob(f"**/{pattern}"):
                if item.is_dir():
                    # 查找README文件
                    readme_file = None
                    if language == 'zh':
                        readme_file = item / "README_zh.md"
                        if not readme_file.exists():
                            readme_file = item / "README.md"
                    else:
                        readme_file = item / "README.md"
                        if not readme_file.exists():
                            readme_file = item / "README_zh.md"
                    
                    if readme_file and readme_file.exists():
                        # 提取项目名称
                        project_name = self._extract_project_name(readme_file, language)
                        projects.append({
                            'name': project_name,
                            'path': readme_file.relative_to(docs_dir),
                            'headings': self.extract_headings_from_markdown(readme_file)
                        })
        
        # 生成目录内容
        toc_lines = [f"{category_name}", "=" * len(category_name), ""]
        
        for project in projects:
            toc_lines.append(f".. toctree::")
            toc_lines.append(f"   :maxdepth: 3")
            toc_lines.append(f"   :caption: {project['name']}")
            toc_lines.append(f"")
            toc_lines.append(f"   {project['path'].with_suffix('')}")
            toc_lines.append(f"")
        
        return "\n".join(toc_lines)
    
    def _extract_project_name(self, readme_file: Path, language: str = 'zh') -> str:
        """从README文件中提取项目名称"""
        try:
            with open(readme_file, 'r', encoding='utf-8') as f:
                first_line = f.readline().strip()
            
            # 移除Markdown标题标记
            if first_line.startswith('#'):
                return first_line.lstrip('#').strip()
            
            return first_line
        except Exception:
            return readme_file.parent.name
    
    def get_language_config(self, language: str = 'zh') -> Dict[str, Any]:
        """获取语言特定配置"""
        return {
            'language': language,
            'file_suffix': self.get_file_suffix(language),
            'index_filename': self.get_index_filename(language),
            'project_config': self.get_project_config(language),
            'sphinx_config': self.get_sphinx_config(language),
            'toc_structure': self.get_toc_structure(language)
        }


def main():
    """测试函数"""
    config_path = Path(__file__).parent.parent / 'config.yaml'
    manager = I18nConfigManager(config_path)
    
    print("中文配置:")
    zh_config = manager.get_language_config('zh')
    print(f"  语言: {zh_config['language']}")
    print(f"  文件后缀: {zh_config['file_suffix']}")
    print(f"  索引文件: {zh_config['index_filename']}")
    print(f"  项目名称: {zh_config['project_config']['title']}")
    
    print("\n英文配置:")
    en_config = manager.get_language_config('en')
    print(f"  语言: {en_config['language']}")
    print(f"  文件后缀: {en_config['file_suffix']}")
    print(f"  索引文件: {en_config['index_filename']}")
    print(f"  项目名称: {en_config['project_config']['title']}")
    
    print("\n分类结构:")
    for category in en_config['toc_structure']:
        print(f"  {category['key']}: {category['name']}")


if __name__ == "__main__":
    main()