aszer/etf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加文档创建规范，定义命名格式与头部元信息标准

Browse Source
This commit is contained in:
aszerW
2026-06-21 19:25:32 +08:00
parent c2bd31ac2a
commit 1cb854f2d8
1 changed files with 322 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
docs/文档创建规范.md Normal file
View 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、配置文件、脚本路径）
- [ ] 存放在正确的目录
- [ ] 章节编号规范
- [ ] 代码块指定语言类型
- [ ] 分隔线使用恰当