工具脚本¶

本目录包含文档处理和管理工具脚本。

📋 文件列表¶

文档迁移工具¶

migrate_docs.py - 文档迁移脚本
将原始文档迁移到新结构
支持批量处理
保留元数据
process_notebooks.py - Notebook处理脚本
Jupyter Notebook格式转换
代码提取
依赖分析
create_notebook_indexes.py - Notebook索引生成器
自动生成索引文件
按类别组织
生成导航
test_notebook_render.py - Notebook渲染测试
验证Notebook可渲染性
检查依赖
测试输出

🎯 主要功能¶

1. migrate_docs.py¶

文档迁移工具，用于将文档从旧结构迁移到新结构。

功能特性¶

目录结构迁移 - 重组文件层次
路径更新 - 更新内部链接
元数据保留 - 保留文件元信息
批量处理 - 支持大规模迁移
日志记录 - 详细操作日志

使用示例¶

# 基本用法
python migrate_docs.py --source old_docs --target new_docs

# 干运行（不实际移动文件）
python migrate_docs.py --dry-run

# 详细输出
python migrate_docs.py --verbose

2. process_notebooks.py¶

处理Jupyter Notebook文件。

功能特性¶

格式转换 - .ipynb ↔ .py ↔ .md
代码提取 - 提取代码单元
输出清理 - 清理单元输出
依赖分析 - 分析import依赖
单元测试 - 生成测试用例

使用示例¶

from process_notebooks import NotebookProcessor

# 创建处理器
processor = NotebookProcessor()

# 转换单个文件
processor.convert('notebook.ipynb', 'notebook.py')

# 批量处理
processor.batch_convert(
    directory='notebooks/',
    output_format='python'
)

# 提取代码
code = processor.extract_code('notebook.ipynb')

3. create_notebook_indexes.py¶

为Notebook目录创建索引文件。

功能特性¶

自动扫描 - 扫描目录结构
分类组织 - 按主题分组
生成导航 - 创建导航链接
元数据提取 - 提取标题、描述
模板支持 - 自定义输出格式

使用示例¶

from create_notebook_indexes import IndexGenerator

# 创建索引生成器
generator = IndexGenerator()

# 生成Markdown索引
generator.generate_index(
    directory='notebooks/',
    output='index.md',
    format='markdown'
)

# 生成JSON索引
generator.generate_index(
    directory='notebooks/',
    output='index.json',
    format='json'
)

# 自定义模板
generator.generate_index(
    directory='notebooks/',
    output='index.html',
    template='custom_template.html'
)

4. test_notebook_render.py¶

测试Notebook的可渲染性。

功能特性¶

渲染测试 - 测试Notebook能否正确渲染
依赖检查 - 检查缺失的依赖
执行测试 - 测试代码单元可执行性
错误报告 - 详细的错误信息
批量测试 - 批量验证多个Notebook

使用示例¶

from test_notebook_render import NotebookTester

# 创建测试器
tester = NotebookTester()

# 测试单个Notebook
result = tester.test('example.ipynb')
print(f"可渲染: {result.is_renderable}")
print(f"缺失依赖: {result.missing_dependencies}")

# 批量测试
results = tester.test_directory('notebooks/')

# 生成报告
tester.generate_report(results, 'test_report.html')

🔧 依赖项¶

核心依赖¶

Python 3.7+
nbformat - Jupyter Notebook格式处理
nbconvert - Notebook转换
jupyter - Jupyter核心库

可选依赖¶

papermill - Notebook参数化和执行
pytest - 测试框架
beautifulsoup4 - HTML解析
requests - HTTP请求（检查外部链接）

文档生成¶

jinja2 - 模板引擎
markdown - Markdown处理
yaml - 配置文件

📚 使用场景¶

场景1: 文档重构¶

# 1. 迁移文档到新结构
python migrate_docs.py --source docs_old --target docs_new

# 2. 处理所有Notebook
python process_notebooks.py --input docs_new --convert-all

# 3. 生成索引
python create_notebook_indexes.py --root docs_new

# 4. 验证可渲染性
python test_notebook_render.py --directory docs_new

场景2: 持续集成¶

# .github/workflows/test-docs.yml
name: Test Documentation
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Test Notebooks
        run: |
          python test_notebook_render.py --directory docs/
          python create_notebook_indexes.py --root docs/

场景3: 自动化工作流¶

# 完整的文档处理工作流
from migrate_docs import DocMigrator
from process_notebooks import NotebookProcessor
from create_notebook_indexes import IndexGenerator
from test_notebook_render import NotebookTester

# 1. 迁移文档
migrator = DocMigrator('old/', 'new/')
migrator.migrate()

# 2. 处理Notebook
processor = NotebookProcessor()
processor.batch_convert('new/', format='both')

# 3. 生成索引
generator = IndexGenerator()
generator.generate_index('new/', 'new/index.md')

# 4. 验证
tester = NotebookTester()
results = tester.test_directory('new/')
tester.generate_report(results)

🔍 配置选项¶

migrate_docs.py¶

# migrate_config.yaml
source: "old_docs/"
target: "new_docs/"
exclude:
  - "*.tmp"
  - "*.bak"
  - "__pycache__"
include:
  - "*.md"
  - "*.ipynb"
  - "*.py"
preserve_metadata: true
update_links: true
log_file: "migration.log"

process_notebooks.py¶

# process_config.yaml
input_dir: "notebooks/"
output_dir: "processed/"
formats:
  - python
  - markdown
  - html
clear_outputs: true
extract_images: true
check_dependencies: true

create_notebook_indexes.py¶

# index_config.yaml
template_dir: "templates/"
output_format: "markdown"
sort_by: "title"  # or "date", "category"
include_metadata:
  - title
  - description
  - author
  - tags
recursive: true

📊 最佳实践¶

1. 迁移前准备¶

# 备份原始文档
cp -r docs/ docs_backup/

# 检查文件完整性
find docs/ -type f | wc -l

# 测试迁移
python migrate_docs.py --dry-run --verbose

2. 处理Notebook¶

# 逐步处理，验证每步
processor = NotebookProcessor()

# 先转换一个测试
processor.convert('test.ipynb', 'test.py')

# 验证输出
# 如果正确，再批量处理
processor.batch_convert('notebooks/')

3. 生成索引¶

# 使用有组织的文件名
generator = IndexGenerator()

# 按类别组织
generator.generate_index(
    'notebooks/',
    structure='categorical'  # 或 'flat', 'hierarchical'
)

4. 测试验证¶

# 全面的测试
tester = NotebookTester()

# 严格模式
tester.strict = True

# 检查所有内容
tester.check_execution = True
tester.check_dependencies = True
tester.check_links = True

# 运行测试
results = tester.test_directory('docs/')

🚀 扩展功能¶

自定义迁移规则¶

class CustomMigrator(DocMigrator):
    def custom_transform(self, content):
        # 自定义转换逻辑
        return transformed_content

自定义索引模板¶

<!-- custom_template.html -->
{% for notebook in notebooks %}
<div class="notebook">
  <h2>{{ notebook.title }}</h2>
  <p>{{ notebook.description }}</p>
  <a href="{{ notebook.path }}">查看</a>
</div>
{% endfor %}

自定义测试¶

class CustomTester(NotebookTester):
    def custom_test(self, notebook):
        # 自定义测试逻辑
        return test_result

📝 注意事项¶

备份 - 始终备份原始数据
测试 - 在副本上测试脚本
版本控制 - 使用Git跟踪更改
日志 - 保留详细日志
验证 - 迁移后验证结果

工具脚本¶

📋 文件列表¶

文档迁移工具¶

🎯 主要功能¶

1. migrate_docs.py¶

功能特性¶

使用示例¶

2. process_notebooks.py¶

功能特性¶

使用示例¶

3. create_notebook_indexes.py¶

功能特性¶

使用示例¶

4. test_notebook_render.py¶

功能特性¶

使用示例¶

🔧 依赖项¶

核心依赖¶

可选依赖¶

文档生成¶

📚 使用场景¶

场景1: 文档重构¶

场景2: 持续集成¶

场景3: 自动化工作流¶

🔍 配置选项¶

migrate_docs.py¶

process_notebooks.py¶

create_notebook_indexes.py¶

📊 最佳实践¶

1. 迁移前准备¶

2. 处理Notebook¶

3. 生成索引¶

4. 测试验证¶

🚀 扩展功能¶

自定义迁移规则¶

自定义索引模板¶

自定义测试¶

📝 注意事项¶

🔗 相关资源¶