forked from nudt_dsp/netrans
137 lines
3.5 KiB
Plaintext
137 lines
3.5 KiB
Plaintext
# gen api html & pdf by sphinx
|
||
|
||
netrans 目录结构如下
|
||
```tree
|
||
netrans/
|
||
│
|
||
├── docs/ # Sphinx 项目的根目录
|
||
│ ├── source/ # 源文件目录
|
||
│ │ ├── _static/ # 静态文件（如图片、CSS、JS）
|
||
│ │ ├── _templates/ # 自定义模板
|
||
│ │ ├── conf.py # 配置文件
|
||
│ │ ├── index.rst # 主页文件
|
||
│ │ └── my_module.rst # 其他文档文件
|
||
│ └── build/ # 构建输出目录（生成的 HTML 文件等）
|
||
│
|
||
└── bin/
|
||
└── netrans_cli/
|
||
└── netrans_py/
|
||
```
|
||
|
||
1. `sphinx-quickstart docs/` 快速生成
|
||
2. 修改 `docs/source/conf.py` ,
|
||
|
||
|
||
### *.rst
|
||
|
||
rst, reStructuredText 文件，用于定义文档的结构。通常放在source目录下。
|
||
|
||
rst 是一种和 markdown 类似的语法
|
||
|
||
使用目录树指令 `.. toctree::`，列出其他文档文件。
|
||
|
||
|
||
## 使用 autodoc + Sphinx 实现 python api 文档(html)
|
||
|
||
1. 修改 docs/source/conf.py
|
||
```py3
|
||
# Configuration file for the Sphinx documentation builder.
|
||
#
|
||
# For the full list of built-in configuration values, see the documentation:
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||
|
||
# -- Project information -----------------------------------------------------
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||
|
||
project = 'netrans'
|
||
copyright = '2025, ccyh'
|
||
author = 'xj'
|
||
release = '0.1'
|
||
|
||
# -- General configuration ---------------------------------------------------
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||
|
||
import os
|
||
import sys
|
||
|
||
sys.path.append('../../netrans_py/')
|
||
sys.path.append('../../')
|
||
|
||
# Sphinx 扩展
|
||
extensions = [
|
||
'sphinx.ext.autodoc', # 自动生成文档
|
||
'sphinx.ext.viewcode', # 添加源代码链接
|
||
'sphinx.ext.napoleon', # 支持 NumPy 和 Google 风格的 docstring
|
||
]
|
||
|
||
# 主题
|
||
html_theme = 'sphinx_rtd_theme'
|
||
|
||
templates_path = ['_templates']
|
||
exclude_patterns = []
|
||
|
||
language = 'zh'
|
||
|
||
# -- Options for HTML output -------------------------------------------------
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||
|
||
html_theme = 'alabaster'
|
||
html_static_path = ['_static']
|
||
|
||
source_suffix = {
|
||
'.rst': 'restructuredtext',
|
||
'.md': 'markdown',
|
||
}
|
||
```
|
||
|
||
2. sphinx-apidoc -o docs/source/ .
|
||
生成 netrans_py 下所有的 *.py 的rst, 并添加到index.rst里.
|
||
```text
|
||
# index.rst
|
||
|
||
```
|
||
|
||
3. sphinx-build -b html docs/source docs/build
|
||
|
||
|
||
## 使用 autodoc + Sphinx 实现 python api 文档(pdf)
|
||
1. 在可以生成 html的 基础上, 使用make latexodf 生成 *.tex文件.
|
||
这一步会报错,原因是无法识别中文
|
||
|
||
2.修改 netrans.tex文件
|
||
```
|
||
cd build/latex
|
||
vim netrans.tex
|
||
```
|
||
|
||
在各种usapackage的地方新增:
|
||
```
|
||
\usepackage[UTF8, fontset=ubuntu]{ctex}
|
||
```
|
||
|
||
3. 使用 xelatex 生成pdf
|
||
sphinx使用的是 xelatex 而非 pdflatex
|
||
```
|
||
xelatex netrans.tex
|
||
```
|
||
|
||
|
||
|
||
## 常见报错
|
||
|
||
报错
|
||
```log
|
||
sphinx-quickstart
|
||
Traceback (most recent call last):
|
||
File "/home/xj/app/miniforge3/envs/sphinx/bin/sphinx-quickstart", line 8, in <module>
|
||
sys.exit(main())
|
||
File "/home/xj/app/miniforge3/envs/sphinx/lib/python3.10/site-packages/sphinx/cmd/quickstart.py", line 721, in main
|
||
locale.setlocale(locale.LC_ALL, '')
|
||
File "/home/xj/app/miniforge3/envs/sphinx/lib/python3.10/locale.py", line 620, in setlocale
|
||
return _setlocale(category, locale)
|
||
locale.Error: unsupported locale setting
|
||
```
|
||
|
||
解决:
|
||
export LC_ALL=en_US.UTF-8
|