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'

参考链接

• Sphinx中文手册