docs: 添加文档创建规范，定义命名格式与头部元信息标准
This commit is contained in:
322
docs/文档创建规范.md
Normal file
322
docs/文档创建规范.md
Normal file
@@ -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、配置文件、脚本路径）
|
||||
- [ ] 存放在正确的目录
|
||||
- [ ] 章节编号规范
|
||||
- [ ] 代码块指定语言类型
|
||||
- [ ] 分隔线使用恰当
|
||||
Reference in New Issue
Block a user