# OneScience-doc

**Repository Path**: onescience-ai/onescience-doc

## Basic Information

- **Project Name**: OneScience-doc
- **Description**: onescience-doc 是 OneScience 项目的专用文档仓库，专注于生成和维护用户手册、安装指南、开发案例、模块说明、数据说明等内容。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2025-11-06
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OneScience 文档工程（onescience-doc）

`onescience-doc` 是 OneScience 项目的专用文档仓库，专注于生成和维护用户手册、安装指南、开发案例、模块说明、数据说明等内容。该工程基于 Sphinx 构建，输出静态文档用于网站发布（如 ReadTheDocs、GitHub Pages）。

## 目录

- [项目概述](#项目概述)
- [仓库结构](#仓库结构)
- [快速开始](#快速开始)
- [文档编写](#文档编写)
- [文档构建](#文档构建)
- [自定义配置](#自定义配置)
- [注意事项](#注意事项)
- [贡献指南](#贡献指南)
- [常见问题](#常见问题)
- [参考资料](#参考资料)

## 项目概述

OneScience 是基于先进深度学习框架打造的科学计算平台，聚焦加速科学研究与技术开发进程，深度支持以下领域的研究：

| 领域 | 说明 |
|------|------|
| 地球科学 | 气象预报、气候模拟、地球物理分析 |
| 生命信息 | 蛋白质结构预测、生物序列分析 |
| 计算流体 | 流体力学仿真、湍流建模 |
| 工业仿真 | 工程结构分析、多物理场耦合 |
| 材料化学 | 分子动力学、材料性能预测 |

平台提供标准化的数据集接口、丰富的模块组件（Attention、Encoder/Decoder、Transformer、Embedding 等）、高效的科学计算库，以及 Pangu、FourCastNet、Xihe、Protenix 等领域前沿 SOTA 模型，兼备便利的安装使用体验。

**开源地址**

- GitHub：https://github.com/onescience-ai/OneScience
- Gitee：https://gitee.com/onescience-ai/onescience

**当前版本**：`v0.2.0`

## 仓库结构

```
onescience-doc/
├── images/                       # 文档中引用图片资源
├── source/                       # 文档源文件目录（rst/markdown）
│   ├── conf.py                   # Sphinx 配置文件
│   ├── index.rst                 # 文档入口
│   ├── 安装手册/                 # 安装、环境配置、GPU/DCU 平台适配
│   ├── 开发案例/                 # 示例代码、快速启动流程、训练/推理脚本
│   ├── 模块列表/                 # 模块接口、API 说明（自动生成）
│   ├── 热点模型/                 # 核心模型介绍（Pangu、Xihe、Protenix 等）
│   └── 数据说明/                 # 数据集描述、格式要求、预处理方法
├── generate_docs.sh              # 一键生成脚本
├── Makefile                      # 构建入口
├── QUICKSTART.md                 # 快速开始文档
├── requirements.txt              # Python 依赖列表
└── readme.md                     # 当前说明文档
```

## 快速开始

### 安装方法

1. 克隆仓库：

```bash
git clone https://github.com/hpccube/OneScience-doc.git
cd onescience-doc
```

2. 安装依赖：

```bash
pip install -r requirements.txt
pip install myst-parser  # Markdown 支持（需单独安装）
```

3. 生成文档：

**方式一：使用一键脚本（推荐）**

```bash
./generate_docs.sh
```

该脚本会自动检查并安装 Sphinx、生成 HTML 文档，并尝试在浏览器中打开。

**方式二：手动构建**

```bash
make html
```

4. 查看文档：

```bash
open build/html/index.html      # Mac
xdg-open build/html/index.html  # Linux
start build/html/index.html     # Windows
```

5. 本地预览（带实时刷新）：

```bash
sphinx-autobuild source build/html
# 浏览器打开 http://127.0.0.1:8000
```

## 文档编写

### 目录说明

| 目录 | 内容 |
|------|------|
| `source/安装手册/` | 安装与环境配置，包含 GPU、DCU 平台适配指南 |
| `source/开发案例/` | 示例代码与使用流程，含快速启动、训练推理脚本 |
| `source/模块列表/` | 模块目录与接口说明（Attention、Encoder、Transformer 等） |
| `source/热点模型/` | Pangu、FourCastNet、Xihe、Protenix 等前沿模型介绍 |
| `source/数据说明/` | 数据集描述、格式要求与预处理方法 |

### 写作规范

- 文字首选中文，英文术语保持清晰
- 代码和配置用代码块展示（Markdown/reStructuredText）
- 新增页面必须在相关 `toctree` 中注册
- 文档中添加必要示例（运行命令、完整代码片段、输出说明）
- Docstring 使用 Google 或 NumPy 风格，兼容 Sphinx `autodoc`（`napoleon`）

### 注释格式说明

#### reStructuredText 风格

```python
def my_function(param1, param2):
    """
    函数简短描述

    :param param1: 参数1的说明
    :type param1: str
    :param param2: 参数2的说明
    :type param2: int
    :return: 返回值说明
    :rtype: bool
    """
    pass
```

#### Google 风格

```python
def my_function(param1, param2):
    """函数简短描述

    Args:
        param1 (str): 参数1的说明
        param2 (int): 参数2的说明

    Returns:
        bool: 返回值说明
    """
    pass
```

### 添加自己的模块

#### 步骤 1：在 source/ 下创建文档文件

```markdown
<!-- source/模块列表/my_module.md -->
# 我的模块说明

## 功能描述

这个模块用于...

## 使用示例

```python
from onescience.modules.my_module import my_function

result = my_function(x)
```
```

#### 步骤 2：添加到模块列表

编辑 `source/模块列表/index.md`，在 `toctree` 中添加：

```markdown
    my_module
```

#### 步骤 3：重新生成文档

```bash
make html
```

### 生成 API 文档

使用 `sphinx-apidoc` 从源码自动提取 docstring：

```bash
sphinx-apidoc -f -e -M -o source/模块列表/ ../src/需要扫描的代码目录
```

参数说明：
- `-f`：强制覆盖已有文件
- `-e`：每个模块单独生成一个文件
- `-M`：将模块文档放在同名目录中

## 文档构建

### 常用构建命令

```bash
make html          # 生成 HTML 文档
make clean         # 清理生成的文件
make latexpdf      # 生成 PDF 文档（需要 LaTeX）
make linkcheck     # 检查文档中的外部链接
```

### 实时预览

```bash
pip install sphinx-autobuild
sphinx-autobuild source build/html
```

### 线上部署

- **GitHub Actions**：配置 CI 执行 `make html`，将 `build/html` 部署到 GitHub Pages
- **ReadTheDocs**：直接连接仓库，配置 `source/` 目录自动构建

## 自定义配置

在 `source/conf.py` 中可以：

- 修改主题：`html_theme = 'sphinx_rtd_theme'`
- 添加扩展：在 `extensions` 列表中添加插件
- 配置 autodoc 行为：修改 `autodoc_default_options`
- 启用中文支持：`language = 'zh_CN'`
- Mock 缺失依赖：`autodoc_mock_imports = ['numpy', 'torch']`

### 可选主题

| 主题 | 安装命令 | 说明 |
|------|----------|------|
| `alabaster` | 内置 | Sphinx 默认主题 |
| `sphinx_rtd_theme` | `pip install sphinx-rtd-theme` | Read the Docs 风格（当前使用） |
| `pydata_sphinx_theme` | `pip install pydata-sphinx-theme` | 数据科学风格 |
| `furo` | `pip install furo` | 现代简洁风格 |

## 注意事项

1. **路径配置**：`source/conf.py` 中的 `sys.path.insert(0, ...)` 必须正确指向源代码目录
2. **必须使用 docstring**：只有三引号的文档字符串（`"""`）会被提取，普通注释 `#` 不会
3. **模块须可导入**：代码必须能被正常导入，否则 `autodoc` 无法工作
4. **中文支持**：在 `source/conf.py` 中确认设置 `language = 'zh_CN'`
5. **Markdown 支持**：使用 `.md` 文件时需安装 `myst-parser` 并在 `extensions` 中添加 `'myst_parser'`

## 贡献指南

1. Fork 仓库，新建分支 `feat/docs/<topic>`
2. 补充文档及示例
3. 运行测试（若有）：`pytest tests/`
4. 提交 PR，标题格式：`docs: <描述>`
5. CI 检查通过后合并

## 常见问题

| 问题 | 解决方法 |
|------|----------|
| `make html` 失败 | 安装依赖：`pip install sphinx sphinx-rtd-theme myst-parser sphinx-autobuild` |
| 导入模块失败 | 在 `source/conf.py` 中添加 `sys.path.insert(0, os.path.abspath('../../src'))` |
| 文档内容未更新 | 执行 `make clean` 后再 `make html` |
| 文档内容为空 | 检查是否使用了 docstring（三引号），而非 `#` 注释 |
| 中文显示乱码 | 在 `source/conf.py` 中设置 `language = 'zh_CN'` |
| 缺少第三方库 | 在 `source/conf.py` 中 mock 导入：`autodoc_mock_imports = ['numpy', 'torch']` |
| Markdown 文件不渲染 | 确认已安装 `myst-parser` 且 `extensions` 中包含 `'myst_parser'` |

## 参考资料

- [Sphinx 官网](https://www.sphinx-doc.org/)
- [reStructuredText 语法](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
- [autodoc 扩展](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
- [MyST Parser 文档](https://myst-parser.readthedocs.io/)
- [ReadTheDocs 主题](https://sphinx-rtd-theme.readthedocs.io/)
- [Conventional Commits](https://www.conventionalcommits.org/)