diff --git a/docs/文档创建规范.md b/docs/文档创建规范.md new file mode 100644 index 0000000..3b8aaa1 --- /dev/null +++ b/docs/文档创建规范.md @@ -0,0 +1,322 @@ +# ETF轮动项目文档创建规范 + +> 规范版本:v1.0 +> 制定日期:2026-06-21 + +--- + +## 1. 文件命名规范 + +### 1.1 基本格式 + +``` +YYYYMMDD_中文名称.md +``` + +- **日期来源**:文档首次创建的git提交日期 +- **命名原则**:日期前缀 + 简洁中文描述 +- **禁止字符**:空格、特殊符号(除 `_` 和 `-`) + +### 1.2 命名示例 + +| 类型 | 示例 | +|------|------| +| 分析报告 | `20260607_select_num_1深度分析.md` | +| 调研报告 | `20260606_动量因子对比调研.md` | +| 实验记录 | `20260617_010_起始年份敏感性分析.md` | +| 架构设计 | `20260507_通用数据源架构.md` | +| 核心逻辑 | `20260430_轮动策略核心逻辑.md` | +| 版本迭代 | `20260519_轮动策略核心逻辑_v3.md` | + +### 1.3 特殊场景 + +- **实验编号**:experiments目录下保留编号前缀,格式 `YYYYMMDD_编号_名称.md` +- **版本号**:迭代版本在末尾加 `_vN`,如 `_v2`、`_v3` +- **Git标识**:阶段性总结可带commit hash,如 `_ca933e4` + +--- + +## 2. 文档分类与头部格式 + +### 2.1 分析报告类 + +**适用场景**:策略分析、回测分析、深度分析 + +**头部格式**: + +```markdown +# [报告标题] + +> 分析日期:YYYY-MM-DD +> 策略版本:[配置文件/代码版本说明] +> 回测区间:YYYY-MM-DD ~ YYYY-MM-DD(约 N 个交易日) + +## 1. [章节标题] +... +``` + +**必填字段**: +- 分析日期:文档创建日期 +- 策略版本:基于的配置文件或代码版本 +- 回测区间:数据时间范围 + +--- + +### 2.2 调研报告类 + +**适用场景**:技术调研、因子调研、文献综述 + +**头部格式**: + +```markdown +# [调研标题] + +> 调研日期:YYYY-MM-DD +> 回测区间:YYYY-MM-DD ~ YYYY-MM-DD(可选) +> 当前结论:[核心发现摘要] + +--- + +## 1. [章节标题] +... +``` + +**必填字段**: +- 调研日期:文档创建日期 + +**可选字段**: +- 回测区间:如有回测实验 +- 当前结论:调研核心发现 + +--- + +### 2.3 实验记录类(experiments目录) + +**适用场景**:对比实验、参数优化、敏感性分析 + +**头部格式**: + +```markdown +# 实验记录 XXX: [实验名称] + +## 实验信息 + +| 项目 | 内容 | +|------|------| +| 实验编号 | XXX | +| 实验日期 | YYYY-MM-DD | +| 实验类型 | [类型分类] | +| 研究问题 | [问题描述] | +| 配置文件 | `[配置路径]` | +| 实验脚本 | `[脚本路径]` | + +--- + +## 1. 实验背景 +... +``` + +**必填字段**: +- 实验编号:三位数字,如 001、010 +- 实验日期:文档创建日期 +- 实验类型:如"参数优化"、"对比实验"、"敏感性分析" +- 研究问题:一句话描述研究目标 +- 配置文件:使用的配置文件路径 +- 实验脚本:运行的脚本路径 + +--- + +### 2.4 技术架构类 + +**适用场景**:系统架构、模块设计、接口说明 + +**头部格式**: + +```markdown +# [模块名称] - 架构设计 + +## 设计目标 + +[设计目标描述] + +## 整体架构 + +[架构图或说明] +... +``` + +**说明**:架构类文档以设计目标开篇,无需元信息块 + +--- + +### 2.5 核心逻辑类 + +**适用场景**:策略核心逻辑、算法说明、版本迭代 + +**头部格式**: + +```markdown +# [策略名称]核心逻辑 [版本号] + +## 📊 策略概览 + +[策略概述] + +--- + +## [章节标题] +... +``` + +**说明**: +- 使用emoji增强章节可读性 +- 版本迭代文档需包含版本对比章节 + +--- + +### 2.6 阶段性总结类(strategy_summaries目录) + +**适用场景**:策略阶段总结、版本快照 + +**头部格式**: + +```markdown +# [策略名称]阶段总结 + +> **生成日期**:YYYY-MM-DD +> **Git Commit**:`commit_hash` +> **复现方式**:`git checkout xxx` 后运行 `[脚本路径]` + +--- + +## 1. 策略概述 +... +``` + +**必填字段**: +- 生成日期:快照生成日期 +- Git Commit:代码版本hash +- 复现方式:如何复现该版本的完整命令 + +--- + +## 3. Git可复现性规范 + +### 3.1 核心原则 + +> **所有实验、分析结果必须可通过Git历史精确复现** + +### 3.2 必须记录的信息 + +| 信息类型 | 记录位置 | 示例 | +|----------|----------|------| +| 配置文件 | 元信息块 | `config_simple.yaml` | +| 代码版本 | 元信息块或正文 | `ca933e4` | +| 实验脚本 | 实验信息表 | `rotation/simple_rotation.py` | +| 数据范围 | 元信息块 | `2020-01-10 ~ 2026-06-05` | + +### 3.3 复现命令示例 + +```bash +# 切换到指定版本 +git checkout ca933e4 + +# 运行实验脚本 +python rotation/simple_rotation.py --config rotation/config_simple.yaml +``` + +--- + +## 4. 内容结构规范 + +### 4.1 章节编号 + +- 主章节:`## 1.`、`## 2.`、`## 3.` +- 子章节:`### 1.1`、`### 1.2` +- 段落要点:使用有序或无序列表 + +### 4.2 分隔线使用 + +- 元信息块与正文之间:使用 `---` 分隔 +- 不同主题章节之间:可选使用 `---` 分隔 + +### 4.3 表格格式 + +```markdown +| 列名1 | 列名2 | 列名3 | +|------|------|------| +| 内容1 | 内容2 | 内容3 | +``` + +- 表头使用粗体或自然加粗 +- 内容左对齐,数值列可右对齐 + +### 4.4 代码块格式 + +```markdown +```python +# 代码示例 +def example(): + pass +\``` +``` + +- 指定语言类型 +- 关键代码需有注释说明 + +--- + +## 5. 文档存放目录 + +### 5.1 目录结构 + +``` +docs/ +├── YYYYMMDD_文档名称.md # 通用文档 +├── experiments/ # 实验记录 +│ └── YYYYMMDD_XXX_实验名称.md +├── strategy_summaries/ # 阶段性总结 +│ └── YYYYMMDD_策略快照_hash.md +└── 文档创建规范.md # 本规范文档(例外:无日期前缀) +``` + +### 5.2 目录选择原则 + +| 文档类型 | 存放目录 | +|----------|----------| +| 策略分析、调研报告 | docs/ | +| 实验记录、对比测试 | docs/experiments/ | +| 策略阶段总结、版本快照 | docs/strategy_summaries/ | + +--- + +## 6. 例外情况 + +### 6.1 规范文档本身 + +- 规范文档不使用日期前缀 +- 文件名:`文档创建规范.md` + +### 6.2 README文件 + +- 目录说明文件命名为 `README.md` +- 无需日期前缀 + +### 6.3 从其他位置迁移的文档 + +- 如无法确定原始创建日期,使用迁移日期 +- 在元信息中注明"迁移自[原位置]" + +--- + +## 7. 检查清单 + +创建新文档时,确认以下事项: + +- [ ] 文件名符合 `YYYYMMDD_中文名称.md` 格式 +- [ ] 头部元信息完整(根据文档类型) +- [ ] Git可复现信息已记录(commit hash、配置文件、脚本路径) +- [ ] 存放在正确的目录 +- [ ] 章节编号规范 +- [ ] 代码块指定语言类型 +- [ ] 分隔线使用恰当 \ No newline at end of file