此sphinx可不是彼sphinx,此篇是指生成文档的工具,是python下最流行的文档生成工具,python官方文档即是它生成,官方网站是http://www.sphinx-doc.org,这里是一个中文翻译站:https://zh-sphinx-doc.readthedocs.io

readthedocs.org(下文简称rtd)是一个基于sphinx、mkdocs的在线文档托管网站,支持git、subversion等版本控制系统,并提供多版本、翻译、下载文档等,颇受欢迎。

此篇文章记录了本人使用sphinx和rtd的经验,以Flask-PluginKit为例,文档地址是https://flask-pluginkit.readthedocs.io

一、新项目整体流程

0. 说在前面

    $project - 项目名可见名,比如Flask-PluginKit,$package - 项目包名,比如flask_pluginkit

    $author - 作者

    $src - reStructuredText源文档目录

1. 安装依赖

    pip install sphinx

2. 初始化项目文档

    使用sphinx-quickstart,网上很多例子,这里说一个无交互,按例子:

    sphinx-quickstart -q -p $project -a $author --ext-autodoc --ext-viewcode --no-makefile --no-batchfile $src

3. 从项目中提取接口文档

    sphinx-apidoc -d 2 -f --ext-autodoc --ext-viewcode --private -o $src $package

4. 生成html文件

    第三步中,根据包中函数、类等注释会生成.rst文件,你可以编写组织它们,然后生成html文件:

    cd $src && sphinx-build -b html . _build/html

5. 说在后面

    修改过rst文件后可以多次生成html文件,默认只有更新过的文件才会重新生成html。生成的html静态文件可以放到github pages或任何支持静态访问的web服务器中。

二、翻译

sphinx支持你给文档添加翻译以支持国际化功能,使用工具sphinx-intl,安装它:pip install sphinx-intl

详细使用可以参考这篇文章,以下简单流程是将中文翻译成英文的。

1. gettext-初始化翻译

    cd $src && sphinx-build -b gettext . _build/locale

2. 更新翻译

    cd $src && sphinx-intl update -p _build/locale/ -l en

3. 生成翻译文档

    cd $src && sphinx-build -D language=en -b html . _build/html_en

三、托管

sphinx生成接口文档+github托管源代码+rtd在线托管文档,简单爽的不要不要的,提交后自动构建并生成文档,美滋滋。

使用github登录可以选择项目导入,自动添加webhook,使用不介绍,这里提一个翻译的经验。

1. rtd同一个项目同时支持多种翻译

    rtd的支持翻译,但是需要添加某个项目为翻译版本,比如著名的requests,就有很多翻译,每个翻译是一个git仓库,都需要维护。

    但是有时候我们就一个项目不想那么麻烦,而且一个项目使用sphinx-intl添加了翻译支持,那么怎么处理呢?

    其实简单,rtb导入一个项目,选择手动导入,设置不同名称、相同代码库地址,然后文档主项目设置此项目为翻译版本即可,嗯,点到即止,参考上面Flask-PluginKit的文档地址。




·End·