此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的文档地址。