291 lines
9.9 KiB
Python
291 lines
9.9 KiB
Python
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
"""
|
||
自动将docs目录下的文件添加到mkdocs.yml导航配置中
|
||
"""
|
||
|
||
import os
|
||
import sys
|
||
import re
|
||
import yaml
|
||
from pathlib import Path
|
||
|
||
def load_mkdocs_nav(mkdocs_path='mkdocs.yml'):
|
||
"""加载mkdocs.yml中的导航配置"""
|
||
try:
|
||
with open(mkdocs_path, 'r', encoding='utf-8') as f:
|
||
content = f.read()
|
||
|
||
# 使用正则表达式提取nav部分
|
||
nav_match = re.search(r'nav:\s*\n(.*?)(?=\n\w+:|$)', content, re.DOTALL)
|
||
if not nav_match:
|
||
print("错误: 找不到nav配置")
|
||
sys.exit(1)
|
||
|
||
nav_content = nav_match.group(1)
|
||
|
||
# 解析YAML格式的nav内容
|
||
# 为nav内容添加适当的缩进
|
||
nav_yaml = "nav:\n" + nav_content
|
||
config = yaml.safe_load(nav_yaml)
|
||
return config.get('nav', [])
|
||
|
||
except FileNotFoundError:
|
||
print(f"错误: 找不到文件 {mkdocs_path}")
|
||
sys.exit(1)
|
||
except Exception as e:
|
||
print(f"错误: 解析文件失败: {e}")
|
||
sys.exit(1)
|
||
|
||
def save_mkdocs_nav(nav, mkdocs_path='mkdocs.yml'):
|
||
"""保存导航配置到mkdocs.yml"""
|
||
try:
|
||
with open(mkdocs_path, 'r', encoding='utf-8') as f:
|
||
content = f.read()
|
||
|
||
# 生成新的nav内容
|
||
nav_yaml = yaml.dump({'nav': nav}, allow_unicode=True, default_flow_style=False, sort_keys=False)
|
||
|
||
# 移除第一行的"nav:"
|
||
nav_lines = nav_yaml.split('\n')
|
||
new_nav_content = '\n'.join(nav_lines[1:]) # 跳过第一行
|
||
|
||
# 替换原有的nav部分，使用re.escape避免特殊字符问题
|
||
nav_pattern = r'(nav:\s*\n)(.*?)(?=\n\w+:|$)'
|
||
# 对new_nav_content进行转义处理
|
||
escaped_content = re.escape(new_nav_content)
|
||
# 但我们需要保留实际的换行符等，所以使用更简单的方法
|
||
new_content = re.sub(nav_pattern, r'\1' + new_nav_content, content, flags=re.DOTALL)
|
||
|
||
with open(mkdocs_path, 'w', encoding='utf-8') as f:
|
||
f.write(new_content)
|
||
|
||
print(f"✓ 已更新 {mkdocs_path}")
|
||
|
||
except Exception as e:
|
||
print(f"错误: 保存文件失败: {e}")
|
||
sys.exit(1)
|
||
|
||
def get_all_md_files(docs_dir='docs'):
|
||
"""获取docs目录下的所有.md文件"""
|
||
md_files = []
|
||
for root, dirs, files in os.walk(docs_dir):
|
||
for file in files:
|
||
if file.endswith('.md'):
|
||
rel_path = os.path.relpath(os.path.join(root, file), docs_dir)
|
||
# 将Windows路径分隔符转换为Unix风格（/）
|
||
rel_path = rel_path.replace('\\', '/')
|
||
md_files.append(rel_path)
|
||
return sorted(md_files)
|
||
|
||
def get_nav_files(nav):
|
||
"""从导航配置中提取所有文件路径"""
|
||
nav_files = []
|
||
|
||
def extract_files(item):
|
||
if isinstance(item, dict):
|
||
for key, value in item.items():
|
||
if isinstance(value, list):
|
||
for subitem in value:
|
||
extract_files(subitem)
|
||
elif isinstance(value, str):
|
||
nav_files.append(value)
|
||
elif isinstance(item, str):
|
||
nav_files.append(item)
|
||
|
||
for item in nav:
|
||
extract_files(item)
|
||
|
||
return nav_files
|
||
|
||
def categorize_file(file_path):
|
||
"""根据文件路径分类文件"""
|
||
path_parts = file_path.split('/')
|
||
|
||
# 如果文件在根目录
|
||
if len(path_parts) == 1:
|
||
return "其他"
|
||
|
||
# 根据目录名分类
|
||
category_map = {
|
||
'技术文档': '技术文档',
|
||
'开发指南': '开发指南',
|
||
'学习笔记': '学习笔记',
|
||
'DevOps平台': 'DevOps平台',
|
||
'cursor': 'Cursor工具',
|
||
'Obsidian': 'Obsidian笔记'
|
||
}
|
||
|
||
first_dir = path_parts[0]
|
||
# 如果目录名在映射中，使用映射的名称，否则使用目录名
|
||
return category_map.get(first_dir, first_dir)
|
||
|
||
def remove_deleted_files_from_nav(nav, existing_files=None, docs_dir='docs'):
|
||
"""从导航配置中删除已不存在的文件"""
|
||
deleted_files = []
|
||
|
||
def clean_item(item):
|
||
"""递归清理导航项，删除不存在的文件"""
|
||
if isinstance(item, dict):
|
||
# 处理字典类型（分类）
|
||
cleaned_dict = {}
|
||
for key, value in item.items():
|
||
if isinstance(value, list):
|
||
# 递归处理列表
|
||
cleaned_list = []
|
||
for subitem in value:
|
||
cleaned = clean_item(subitem)
|
||
if cleaned is not None:
|
||
cleaned_list.append(cleaned)
|
||
|
||
# 如果列表不为空，保留分类
|
||
if cleaned_list:
|
||
cleaned_dict[key] = cleaned_list
|
||
elif isinstance(value, str):
|
||
# 检查文件是否存在
|
||
file_path = os.path.join(docs_dir, value.replace('/', os.sep))
|
||
if os.path.exists(file_path) or value == 'index.md':
|
||
cleaned_dict[key] = value
|
||
else:
|
||
deleted_files.append(value)
|
||
else:
|
||
# 其他类型，保留
|
||
cleaned_dict[key] = value
|
||
|
||
# 如果字典为空，返回None表示删除
|
||
return cleaned_dict if cleaned_dict else None
|
||
elif isinstance(item, str):
|
||
# 检查文件是否存在
|
||
file_path = os.path.join(docs_dir, item.replace('/', os.sep))
|
||
if os.path.exists(file_path) or item == 'index.md':
|
||
return item
|
||
else:
|
||
deleted_files.append(item)
|
||
return None
|
||
else:
|
||
# 其他类型，保留
|
||
return item
|
||
|
||
# 处理导航列表
|
||
new_nav = []
|
||
for item in nav:
|
||
cleaned = clean_item(item)
|
||
if cleaned is not None:
|
||
new_nav.append(cleaned)
|
||
|
||
return new_nav, deleted_files
|
||
|
||
def add_files_to_nav(nav, missing_files):
|
||
"""将缺失的文件添加到导航配置中"""
|
||
# 创建分类字典
|
||
categories = {}
|
||
for file_path in missing_files:
|
||
category = categorize_file(file_path)
|
||
if category not in categories:
|
||
categories[category] = []
|
||
categories[category].append(file_path)
|
||
|
||
# 将文件添加到现有分类或创建新分类
|
||
for category, files in categories.items():
|
||
category_found = False
|
||
|
||
# 查找是否已存在该分类
|
||
for i, item in enumerate(nav):
|
||
if isinstance(item, dict) and category in item:
|
||
# 添加到现有分类
|
||
existing_files = set(item[category])
|
||
for file_path in files:
|
||
if file_path not in existing_files:
|
||
item[category].append(file_path)
|
||
category_found = True
|
||
print(f"✓ 已将 {len(files)} 个文件添加到 '{category}' 分类")
|
||
break
|
||
|
||
# 如果分类不存在，创建新分类
|
||
if not category_found:
|
||
nav.append({category: sorted(files)})
|
||
print(f"✓ 已创建新分类 '{category}' 并添加 {len(files)} 个文件")
|
||
|
||
return nav
|
||
|
||
def main():
|
||
print("开始自动同步docs目录和mkdocs.yml导航配置...")
|
||
print("=" * 60)
|
||
|
||
# 1. 加载当前导航配置
|
||
print("1. 加载mkdocs.yml导航配置...")
|
||
nav = load_mkdocs_nav()
|
||
|
||
# 2. 获取所有.md文件
|
||
print("2. 扫描docs目录下的所有.md文件...")
|
||
all_md_files = get_all_md_files()
|
||
print(f" 找到 {len(all_md_files)} 个.md文件")
|
||
|
||
# 3. 获取导航中的文件
|
||
print("3. 分析当前导航配置...")
|
||
nav_files = get_nav_files(nav)
|
||
print(f" 导航中已有 {len(nav_files)} 个文件")
|
||
|
||
# 4. 检查并删除已删除的文件
|
||
print("4. 检查已删除的文件...")
|
||
updated_nav, deleted_files = remove_deleted_files_from_nav(nav, all_md_files)
|
||
|
||
if deleted_files:
|
||
print(f" 发现 {len(deleted_files)} 个文件已删除:")
|
||
for i, file_path in enumerate(deleted_files, 1):
|
||
print(f" {i:2d}. {file_path}")
|
||
nav = updated_nav
|
||
# 重新获取导航文件列表（已更新）
|
||
nav_files = get_nav_files(nav)
|
||
else:
|
||
print(" ✓ 没有发现已删除的文件")
|
||
|
||
# 5. 找出缺失的文件（需要添加到导航的）
|
||
missing_files = []
|
||
for md_file in all_md_files:
|
||
# 将路径统一为Unix风格进行比较
|
||
if md_file not in nav_files and md_file != 'index.md':
|
||
missing_files.append(md_file)
|
||
|
||
# 6. 汇总变更
|
||
has_changes = len(deleted_files) > 0 or len(missing_files) > 0
|
||
|
||
if not has_changes:
|
||
print("\n✓ 导航配置已是最新，无需更新")
|
||
return
|
||
|
||
# 显示变更摘要
|
||
print("\n5. 变更摘要:")
|
||
if deleted_files:
|
||
print(f" 将删除 {len(deleted_files)} 个已不存在的文件")
|
||
if missing_files:
|
||
print(f" 将添加 {len(missing_files)} 个新文件:")
|
||
for i, file_path in enumerate(missing_files, 1):
|
||
print(f" {i:2d}. {file_path}")
|
||
|
||
# 7. 确认是否继续
|
||
print("\n6. 是否继续更新mkdocs.yml？")
|
||
response = input(" 输入 'y' 继续，其他键取消: ")
|
||
|
||
if response.lower() != 'y':
|
||
print("操作已取消")
|
||
return
|
||
|
||
# 8. 添加文件到导航
|
||
print("\n7. 正在更新mkdocs.yml...")
|
||
if missing_files:
|
||
updated_nav = add_files_to_nav(updated_nav, missing_files)
|
||
|
||
# 9. 保存配置
|
||
save_mkdocs_nav(updated_nav)
|
||
|
||
print("\n" + "=" * 60)
|
||
print("完成！mkdocs.yml已更新")
|
||
if deleted_files:
|
||
print(f"删除了 {len(deleted_files)} 个已不存在的文件")
|
||
if missing_files:
|
||
print(f"添加了 {len(missing_files)} 个新文件到导航中")
|
||
|
||
if __name__ == '__main__':
|
||
main()
|