onescience-doc 是 OneScience 项目的专用文档仓库，专注于生成和维护用户手册、安装指南、开发案例、模块说明、数据说明等内容。该工程基于 Sphinx 构建，输出静态文档用于网站发布（如 ReadTheDocs、GitHub Pages）。
OneScience 是基于先进深度学习框架打造的科学计算平台，聚焦加速科学研究与技术开发进程，深度支持以下领域的研究：
| 领域 | 说明 |
|---|---|
| 地球科学 | 气象预报、气候模拟、地球物理分析 |
| 生命信息 | 蛋白质结构预测、生物序列分析 |
| 计算流体 | 流体力学仿真、湍流建模 |
| 工业仿真 | 工程结构分析、多物理场耦合 |
| 材料化学 | 分子动力学、材料性能预测 |
平台提供标准化的数据集接口、丰富的模块组件（Attention、Encoder/Decoder、Transformer、Embedding 等）、高效的科学计算库，以及 Pangu、FourCastNet、Xihe、Protenix 等领域前沿 SOTA 模型，兼备便利的安装使用体验。
开源地址
当前版本：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 # 当前说明文档
- 克隆仓库：
git clone https://github.com/hpccube/OneScience-doc.git
cd onescience-doc- 安装依赖：
pip install -r requirements.txt
pip install myst-parser # Markdown 支持（需单独安装）- 生成文档：
方式一：使用一键脚本（推荐）
./generate_docs.sh该脚本会自动检查并安装 Sphinx、生成 HTML 文档，并尝试在浏览器中打开。
方式二：手动构建
make html- 查看文档：
open build/html/index.html # Mac
xdg-open build/html/index.html # Linux
start build/html/index.html # Windows- 本地预览（带实时刷新）：
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）
def my_function(param1, param2):
"""
函数简短描述
:param param1: 参数1的说明
:type param1: str
:param param2: 参数2的说明
:type param2: int
:return: 返回值说明
:rtype: bool
"""
passdef my_function(param1, param2):
"""函数简短描述
Args:
param1 (str): 参数1的说明
param2 (int): 参数2的说明
Returns:
bool: 返回值说明
"""
pass<!-- 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
make html使用 sphinx-apidoc 从源码自动提取 docstring：
sphinx-apidoc -f -e -M -o source/模块列表/ ../src/需要扫描的代码目录参数说明：
-f：强制覆盖已有文件-e：每个模块单独生成一个文件-M：将模块文档放在同名目录中
make html # 生成 HTML 文档
make clean # 清理生成的文件
make latexpdf # 生成 PDF 文档（需要 LaTeX）
make linkcheck # 检查文档中的外部链接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 |
现代简洁风格 |
- 路径配置：
source/conf.py中的sys.path.insert(0, ...)必须正确指向源代码目录 - 必须使用 docstring：只有三引号的文档字符串（
"""）会被提取，普通注释#不会 - 模块须可导入：代码必须能被正常导入，否则
autodoc无法工作 - 中文支持：在
source/conf.py中确认设置language = 'zh_CN' - Markdown 支持：使用
.md文件时需安装myst-parser并在extensions中添加'myst_parser'
- Fork 仓库，新建分支
feat/docs/<topic> - 补充文档及示例
- 运行测试（若有）：
pytest tests/ - 提交 PR，标题格式：
docs: <描述> - 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' |