Sphinx是一个基于Python的文档生成工具,它可以将标记文本转换为各种格式的文档,包括HTML、PDF、EPUB等。Sphinx最初是为Python文档而开发的,但是它也可以用于其他类型的文档,例如API文档、技术文档、用户手册等。
Sphinx的主要特点包括:
- 支持多种标记语言,包括reStructuredText、Markdown等。
- 支持多种输出格式,包括HTML、PDF、EPUB等。
- 支持自定义主题和样式,可以根据需要进行定制。
- 支持自动生成API文档和代码示例。
- 支持自动生成索引、目录、交叉引用等。
Sphinx的使用方法比较简单,通常包括以下步骤:
- 安装Sphinx
可以使用pip命令安装Sphinx:
pip install sphinx
- 初始化项目
使用sphinx-quickstart命令初始化Sphinx项目,该命令会生成一个包含配置文件和目录结构的项目(建议在项目中新建一个docs目录,在docs目录下执行该命令):
mkdir docs && cd docs
sphinx-quickstart
按照提示输入相关信息
Welcome to the Sphinx 7.0.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y # 是否分离文档源码和生成的HTML
The project name will occur in several places in the built documentation.
> Project name: python-yapi # 项目名称
> Author name(s): Han Zhichao # 作者名称
> Project release []: 0.1.0 # 项目版本
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: en # 语言
Creating file /Users/superhin/Projects/python-yapi/docs/source/conf.py.
Creating file /Users/superhin/Projects/python-yapi/docs/source/index.rst.
Creating file /Users/superhin/Projects/python-yapi/docs/Makefile.
Creating file /Users/superhin/Projects/python-yapi/docs/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file /Users/superhin/Projects/试验/argparse_demo/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
运行后在docs目录下生成source(文档源码)和build(用于生成HTML文档)目录和Makefile相关文件(用于支持make html
命令)。
source中包含了sphinx的配置文件conf.py
以及文档首页index.rst
。
效果如下图:
- 编写文档
在source目录下编写文档,可以使用reStructuredText或Markdown等标记语言。
reStructuredText格式参考:https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/basics.html
- 生成文档
使用make命令生成文档,例如:
make html
该命令会生成HTML格式的文档,保存在build/html目录下。
Sphinx还提供了丰富的配置选项和插件,可以根据需要进行定制。你可以参考Sphinx官方文档,了解更多详细信息和用法示例。
生成模块文档
使用sphinx-apidoc
命令可以根据Python模块注释自动生成模块文档。
- 修改sphinx配置conf.py,在模块查找路径中添加当前项目根路径。
在conf.py文件头部添加
import os
import sys
sys.path.insert(0, os.path.abspath('../..')) # 将项目根目录添加到模块查找路径中去
在 conf.py扩展配置中添加 'sphinx.ext.autodoc',和 'sphinx.ext.viewcode',
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
]
- sphinx.ext.autodoc:根据代码注释自动生成模块文档。
- sphinx.ext.viewcode:增加
[source]
查看源码功能。
- 在命令行进入docs/目录,使用sphinx-apidoc命令生成python_yapi模块文档到source目录
cd docs
sphinx-apidoc -o source ../python_yapi
执行后在source目录下生成modules.rst和python_yapi.rst, 如下图:
在index.rst内容列表中添加modules
在docs目录,命令行使用make html生成文档,使用浏览器打开build/html目录的index.html
使用 readthedoc 主题
原生主题白且单调,可以安装使用sphinx_rtd_theme
- 安装主题
pip install sphinx-rtd-theme
- 使用主题
修改sphinx配置conf.py,导入sphinx_rtd_theme,并修改html_theme及html_theme_path配置
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
- 重新make html生成文档
浏览器打开build/html/index.html,效果如下:
文档托管-发布文档到Readthedocs
- 在项目根目录下新建文件.readthedocs.yaml,指定sphinx配置文件路径,并上传代码到GitHub仓库。
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.9"
sphinx:
configuration: docs/source/conf.py # sphinx配置文件路径
- 打开https://readthedocs.org/ ,使用Github登录(或注册登录)
导入当前项目(或手动导入项目)
点击Build version按钮,成功后点击阅读文档即可查看发布后的文档。
23.cnblogs.com/blog/1064540/202307/1064540-20230706121932687-1626144614.png)
多语言文档(文档翻译)
- 在readthedocs上想要生成支持多语言文档,需要另外新建一个Github项目,如
python-yapi-docs-zh_CN, - 拷贝上一个项目docs及.readthedocs.yaml到当前项目
- 安装sphinx、sphinx-rtd-theme和多语言翻译工具sphinx_intl
pip install sphinx sphinx-rtd-theme sphinx_intl
- 在sphinx配置conf.py中添加语言及国际化目录配置
language = 'zh_CN'
locale_dirs = ['locale/']
- 提取文本及生成待翻译(中文)文本
cd docs/source
sphinx-build -b gettext . locale
sphinx-intl update -p locale -l zh_CN
cd ..
- 手动翻译docs/source/locale/zh_CN/LC_MESSAGES中所有的.po文件,其中msgid是原始英文,msgstr是要翻译的对应的中文,如下图:
注意:不翻译locale目录下的.po文件。
- 在docs目录下使用make html并查看build/html/index.html
效果如下:
- 上传到Github并在readthedocs中导入项目,并设置其语言为Simplified Chinese,如下图:
- 在主项目中添加翻译和子项目
查看文档,将url中的en修改为zh_CN后即可查看中文文档,如下图:
标签:sphinx,docs,生成,source,theme,html,文档 From: https://www.cnblogs.com/superhin/p/sphinx-apidoc.html