Sphinx简介

Sphinx是一个工具,她能够轻易地创建智慧和优雅的文档,她是出自Georg Brandl之手,在BSD许可证下授权。

Sphinx具有如下的特点:

  • 输出格式: 超文本标记语言 (包括Windows HTML帮助),LaTeX (可打印的PDF版本),手册页,纯文本
  • 丰富的交叉引用: 语义标记以及针对函数,类,引用,词汇表(术语)和相似的信息块的自动链接
  • 层次结构: 简单的文本树定义,就能自动地链接到同层(兄弟姐妹)、上一层(父母)以及下一层(子女)的文本位置
  • 自动生成目录: 通用索引以及语言模块的目录
  • 代码高亮: 代码自动高亮,通过使用 Pygments
  • 扩展功能: 自动测试的代码片段,包括从Python模块(API文档)的文档字符串

Sphinx 使用 reStructuredText 作为她的标记语言,她的优点大部分是来自于reStructuredText 以及reStructuredText的解析和转换工具(套件)Docutils的强大以及简单明了。

安装Sphinx

先决条件

Sphinx 运行前需要安装 Python 2.4 或者 Python 3.1 , 以及 docutils 和 Jinja2 库. Sphinx 必须工作在 0.7 版本及一些 SVN 快照(不能损坏). 如果需要源码支持高亮显示,则必须安装 Pygments 库.

如果使用 Python 2.4 ,还需要 uuid.

安装Sphinx

推荐使用pip安装:

pip install Sphinx

配置文档源

文档源是一个包含reStructuredText源文件的目录,官方叫做source diretory,这个目录页包含了Sphinx的配置文件conf.py,在这里你可以配置Sphinx的所有特性,让Sphinx根据你的配置来生成文档.

Shinx有一个脚本sphinx-quickstart可以生成source diretory,它通过几个简单的问题获取一些有用的配置值. 你仅需要运行

sphinx-quickstart

然后根据问题输入你的选择(autodoc扩展一定要回答yes).

尝试生成一个简单的HTML页面

sphinx-build -b html sourcedir builddir

sourcedir 是源目录 source directory , builddir 则是放置生成的文档的根目录. -b 是创建工具的选项;这个例子创建HTML文件.