aszer/etf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1cb854f2d89c8ab48b931fff5ecaf6fa59ffe8d1
etf/docs/文档创建规范.md

6.4 KiB
Raw Blame History

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 分析报告类

适用场景：策略分析、回测分析、深度分析

头部格式：

# [报告标题]

> 分析日期：YYYY-MM-DD
> 策略版本：[配置文件/代码版本说明]
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD（约 N 个交易日）

## 1. [章节标题]
...

必填字段：

  • 分析日期：文档创建日期
  • 策略版本：基于的配置文件或代码版本
  • 回测区间：数据时间范围

2.2 调研报告类

适用场景：技术调研、因子调研、文献综述

头部格式：

# [调研标题]

> 调研日期：YYYY-MM-DD
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD（可选）
> 当前结论：[核心发现摘要]

---

## 1. [章节标题]
...

必填字段：

  • 调研日期：文档创建日期

可选字段：

  • 回测区间：如有回测实验
  • 当前结论：调研核心发现

2.3 实验记录类（experiments目录）

适用场景：对比实验、参数优化、敏感性分析

头部格式：

# 实验记录 XXX: [实验名称]

## 实验信息

| 项目 | 内容 |
|------|------|
| 实验编号 | XXX |
| 实验日期 | YYYY-MM-DD |
| 实验类型 | [类型分类] |
| 研究问题 | [问题描述] |
| 配置文件 | `[配置路径]` |
| 实验脚本 | `[脚本路径]` |

---

## 1. 实验背景
...

必填字段：

  • 实验编号：三位数字，如 001、010
  • 实验日期：文档创建日期
  • 实验类型：如"参数优化"、"对比实验"、"敏感性分析"
  • 研究问题：一句话描述研究目标
  • 配置文件：使用的配置文件路径
  • 实验脚本：运行的脚本路径

2.4 技术架构类

适用场景：系统架构、模块设计、接口说明

头部格式：

# [模块名称] - 架构设计

## 设计目标

[设计目标描述]

## 整体架构

[架构图或说明]
...

说明：架构类文档以设计目标开篇，无需元信息块

2.5 核心逻辑类

适用场景：策略核心逻辑、算法说明、版本迭代

头部格式：

# [策略名称]核心逻辑 [版本号]

## 📊 策略概览

[策略概述]

---

## [章节标题]
...

说明：

  • 使用emoji增强章节可读性
  • 版本迭代文档需包含版本对比章节

2.6 阶段性总结类（strategy_summaries目录）

适用场景：策略阶段总结、版本快照

头部格式：

# [策略名称]阶段总结

> **生成日期**：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 复现命令示例

# 切换到指定版本
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 表格格式

| 列名1 | 列名2 | 列名3 |
|------|------|------|
| 内容1 | 内容2 | 内容3 |
  • 表头使用粗体或自然加粗
  • 内容左对齐，数值列可右对齐

4.4 代码块格式

```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、配置文件、脚本路径）
  • 存放在正确的目录
  • 章节编号规范
  • 代码块指定语言类型
  • 分隔线使用恰当