Skip to content

Commit 9428447

Browse files
dingzhaohandingzhaohan
authored
Merge pull request #12 from hztBUAA/docs
add docs
2 parents d9f08d9 + ac80dc7 commit 9428447

File tree

15 files changed

+1986
-0
lines changed

15 files changed

+1986
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- 'src/**'
9+
- '.github/workflows/docs.yml'
10+
workflow_dispatch: # 允许手动触发
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
deploy-docs:
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v3
22+
with:
23+
fetch-depth: 0 # 需要完整历史用于gh-pages分支
24+
25+
- name: Setup Python
26+
uses: actions/setup-python@v4
27+
with:
28+
python-version: '3.x'
29+
30+
- name: Install dependencies
31+
run: |
32+
pip install -r docs/requirements.txt
33+
pip install -e .
34+
35+
- name: Build documentation
36+
run: |
37+
cd docs
38+
make html
39+
40+
- name: Deploy to GitHub Pages
41+
uses: peaceiris/actions-gh-pages@v3
42+
if: github.ref == 'refs/heads/main'
43+
with:
44+
github_token: ${{ secrets.GITHUB_TOKEN }}
45+
publish_dir: ./docs/build/html
46+
cname: # 如果使用自定义域名，在这里设置，例如: docs.example.com
47+

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ instance/
7070

7171
# Sphinx documentation
7272
docs/_build/
73+
docs/build/
7374

7475
# PyBuilder
7576
.pybuilder/

‎docs/Makefile‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21+

‎docs/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# 文档构建说明
2+
3+
本文档目录包含 Bohrium OpenAPI Python SDK 的完整文档。
4+
5+
## 本地构建
6+
7+
### 前置要求
8+
9+
1. Python 3.7 或更高版本
10+
2. 安装文档依赖：
11+
12+
```bash
13+
pip install -r docs/requirements.txt
14+
```
15+
16+
### 构建HTML文档
17+
18+
```bash
19+
cd docs
20+
make html
21+
```
22+
23+
构建完成后，文档将在 `docs/build/html/index.html`
24+
25+
### 查看文档
26+
27+
在浏览器中打开 `docs/build/html/index.html` 即可查看本地构建的文档。
28+
29+
### 其他构建选项
30+
31+
- `make clean` - 清理构建文件
32+
- `make html` - 构建HTML文档
33+
- `make latexpdf` - 构建PDF文档（需要LaTeX）
34+
- `make help` - 查看所有可用命令
35+
36+
## 自动部署
37+
38+
文档会在推送到 `main` 分支时自动通过 GitHub Actions 构建并部署到 GitHub Pages。
39+
40+
## 文档结构
41+
42+
```
43+
docs/
44+
├── source/ # 文档源文件
45+
│ ├── conf.py # Sphinx配置
46+
│ ├── index.rst # 文档首页
47+
│ ├── installation.rst
48+
│ ├── quickstart.rst
49+
│ ├── tutorial.rst
50+
│ ├── examples.rst
51+
│ ├── faq.rst
52+
│ ├── api/ # API参考文档
53+
│ ├── _static/ # 静态文件
54+
│ └── _templates/ # 自定义模板
55+
├── build/ # 构建输出（不纳入版本控制）
56+
├── Makefile # 构建命令
57+
└── requirements.txt # 文档依赖
58+
```
59+
60+
## 开发建议
61+
62+
1. 使用 `make html` 构建后立即在浏览器中查看，确保格式正确
63+
2. 修改文档后重新构建查看效果
64+
3. 遵循 reStructuredText 格式规范
65+
4. API参考文档通过 `autodoc` 自动从代码生成
66+

‎docs/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx>=5.0.0
2+
sphinx-rtd-theme>=1.2.0
3+

‎docs/source/_static/.gitkeep‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# 此目录用于存放静态文件（CSS、JS、图片等）
2+

‎docs/source/_templates/.gitkeep‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# 此目录用于存放自定义模板文件
2+

‎docs/source/api/reference.rst‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
API参考
2+
========
3+
4+
本文档提供了 Bohrium OpenAPI Python SDK 的完整API参考。
5+
6+
客户端类
7+
--------
8+
9+
.. automodule:: bohrium
10+
:members:
11+
:undoc-members:
12+
:show-inheritance:
13+
14+
主客户端
15+
~~~~~~~~
16+
17+
.. autoclass:: bohrium.Bohrium
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:
21+
22+
异步客户端
23+
~~~~~~~~~~
24+
25+
.. autoclass:: bohrium.AsyncBohrium
26+
:members:
27+
:undoc-members:
28+
:show-inheritance:
29+
30+
基础客户端类
31+
~~~~~~~~~~~~
32+
33+
.. autoclass:: bohrium.SyncAPIClient
34+
:members:
35+
:undoc-members:
36+
:show-inheritance:
37+
38+
.. autoclass:: bohrium.AsyncAPIClient
39+
:members:
40+
:undoc-members:
41+
:show-inheritance:
42+
43+
.. autoclass:: bohrium.BaseClient
44+
:members:
45+
:undoc-members:
46+
:show-inheritance:
47+
48+
资源模块
49+
--------
50+
51+
任务管理 (Job)
52+
~~~~~~~~~~~~~~
53+
54+
.. automodule:: bohrium.resources.job
55+
:members:
56+
:undoc-members:
57+
:show-inheritance:
58+
59+
.. autoclass:: bohrium.resources.job.Job
60+
:members:
61+
:undoc-members:
62+
:show-inheritance:
63+
64+
.. autoclass:: bohrium.resources.job.AsyncJob
65+
:members:
66+
:undoc-members:
67+
:show-inheritance:
68+
69+
Sigma搜索
70+
~~~~~~~~~
71+
72+
.. automodule:: bohrium.resources.sigma_search
73+
:members:
74+
:undoc-members:
75+
:show-inheritance:
76+
77+
.. autoclass:: bohrium.resources.sigma_search.SigmaSearch
78+
:members:
79+
:undoc-members:
80+
:show-inheritance:
81+
82+
.. autoclass:: bohrium.resources.sigma_search.AsyncSigmaSearch
83+
:members:
84+
:undoc-members:
85+
:show-inheritance:
86+
87+
通用解析器
88+
~~~~~~~~~~
89+
90+
.. automodule:: bohrium.resources.uni_parser
91+
:members:
92+
:undoc-members:
93+
:show-inheritance:
94+
95+
.. autoclass:: bohrium.resources.uni_parser.UniParser
96+
:members:
97+
:undoc-members:
98+
:show-inheritance:
99+
100+
.. autoclass:: bohrium.resources.uni_parser.AsyncUniParser
101+
:members:
102+
:undoc-members:
103+
:show-inheritance:
104+
105+
知识库
106+
~~~~~~
107+
108+
.. automodule:: bohrium.resources.knowledge_base
109+
:members:
110+
:undoc-members:
111+
:show-inheritance:
112+
113+
.. autoclass:: bohrium.resources.knowledge_base.KnowledgeBase
114+
:members:
115+
:undoc-members:
116+
:show-inheritance:
117+
118+
.. autoclass:: bohrium.resources.knowledge_base.AsyncKnowledgeBase
119+
:members:
120+
:undoc-members:
121+
:show-inheritance:
122+
123+
论文管理
124+
~~~~~~~~
125+
126+
.. automodule:: bohrium.resources.paper
127+
:members:
128+
:undoc-members:
129+
:show-inheritance:
130+
131+
.. autoclass:: bohrium.resources.paper.Paper
132+
:members:
133+
:undoc-members:
134+
:show-inheritance:
135+
136+
.. autoclass:: bohrium.resources.paper.AsyncPaper
137+
:members:
138+
:undoc-members:
139+
:show-inheritance:
140+
141+
类型定义
142+
--------
143+
144+
任务类型
145+
~~~~~~~~
146+
147+
.. automodule:: bohrium.types.job
148+
:members:
149+
:undoc-members:
150+
:show-inheritance:
151+
152+
Sigma搜索类型
153+
~~~~~~~~~~~~~
154+
155+
.. automodule:: bohrium.types.sigma_search
156+
:members:
157+
:undoc-members:
158+
:show-inheritance:
159+
160+
通用解析器类型
161+
~~~~~~~~~~~~~~
162+
163+
.. automodule:: bohrium.types.uni_parser
164+
:members:
165+
:undoc-members:
166+
:show-inheritance:
167+
168+
知识库类型
169+
~~~~~~~~~~
170+
171+
.. automodule:: bohrium.types.knowledge_base
172+
:members:
173+
:undoc-members:
174+
:show-inheritance:
175+
176+
论文类型
177+
~~~~~~~~
178+
179+
.. automodule:: bohrium.types.paper
180+
:members:
181+
:undoc-members:
182+
:show-inheritance:
183+
184+
异常类
185+
------
186+
187+
.. automodule:: bohrium._exceptions
188+
:members:
189+
:undoc-members:
190+
:show-inheritance:
191+
192+
.. autoexception:: bohrium._exceptions.BohriumError
193+
:members:
194+
:undoc-members:
195+
196+
.. autoexception:: bohrium._exceptions.APIStatusError
197+
:members:
198+
:undoc-members:
199+
200+
工具函数
201+
--------
202+
203+
.. automodule:: bohrium._utils._utils
204+
:members:
205+
:undoc-members:
206+
207+
.. automodule:: bohrium._utils._logs
208+
:members:
209+
:undoc-members:
210+
211+
.. automodule:: bohrium._utils._typing
212+
:members:
213+
:undoc-members:
214+

0 commit comments

Comments
 (0)