Sphinx
Sphinx 🧪
Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档 就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:
- 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本
- 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
- 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
- 美观的自动索引: 可自动生成美观的模块索引
- 精确的语法高亮: 基于 Pygments 自动生成语法高亮
- 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等
Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析，转换等多种工具.
Sphinx quickstart 📓
安装Sphinx：
pip install Sphinx
输入指令，然后回答相关问题.
$ sphinx-quickstart
创建了源目录，包含 conf.py 及一份主文档 index.rst (如果你接受了默认选项).主文档 master document 的主要功能是被 转换成欢迎页, 它包含一个目录表（ “table of contents tree”或者 toctree ).
reStructuredText 📓
Sphinx 主要功能是使用 reStructuredText, 把许多文件组织成一份结构合理的文档.
//toctree 指令初始为空 .. toctree:: :maxdepth: 2 //可以在 content 的位置添加文档列表: .. toctree:: :maxdepth: 2 intro tutorial ...
toctree 是 reStructuredText的 directive （指令）, 一种用途十分广泛的块标记. 定义了参数、选项及目录.
Arguments 直接在双冒号后面给出指令的名字. 每个指令都有不定个数的参数.
Options 在参数后以”字段列表”的形式给出. 如 maxdepth 是 toctree 指令的选项之一.
Content 具体内容,在选项或参数的后面，隔开一个空行. 每个指令后面都跟着不同作用的内容.
共同的约定是 内容与选项一般有相同的缩进 .
构建文档 📓
创建工具 sphinx-build , 使用方式：
$ sphinx-build -b html sourcedir builddir
sourcedir 是源目录 source directory , builddir 则是放置生成的文档的根目录. -b 是创建工具的选项;这个例子创建HTML文件.
方法2：使用sphinx-quickstart 脚本（sphinx-quickstart 脚本创建的 Makefile 和make.bat 使操作更容易）
$ sphinx-autoapi -o /source/ ../src/
$ make html
//or .\make htm
$ make clean
//convert html to pdf
//Sphinx通过Latex间接生成pdf，需要先安装LaTex(2G)
$ make latexpdf
Sphinx自带主题
修改conf.py，将html_theme修改为你想用的主题名字：
thml_theme = 'sphinx_rtd_theme'
参考链接
