用 Sphinx 编写文档

1. 用 Sphinx 编写文档 杜文山 知识淘宝网 软件工程师 电子邮件： du@baow.com 2009年7月25日

2. 演讲内容 • Sphinx 简介 • 功能 • 文档编排方法 • 内容编写方法 • 例子 • 软件安装和运行 • 实际演示 • 高级技巧

3. Sphinx 简介 简介：Sphinx 是一个用Python开发的文档编写工具，能够帮助你编写智能并且美观的文档。编写文档时，只在文本文件中加入一些简单的标记符号(reStructuredText)，然后通过调用命令智能处理，最终生成HTML网页格式或其它格式文件。 英文发音： [sfiŋks] ，【希神】斯芬克斯，[埃]狮身人面 用途：编写文档(C/C++，Java，Python等等)，电子图书，生成静态网页，提高编写和维护文档的效率。 网址：http://sphinx.pocoo.org/ 作者：Georg Brandl 许可协议： BSD 典型用户：Python 官方文档，Django，SQLAlchemy，Zope3等等

4. 功能 • 通过使用 扩展的reStructuredText 标记实现文档的编写 • 支持多种输出格式：HTML (包括Windows HTML Help)，LaTeX，PDF • 智能的链接引用 函数、类等等程序代码中的信息 • 轻松的定义文档的层次结构，并做出相应的链接，比如：上一页，下一样等等功能。 • 自动生成索引 • 代码自动处理，通过Pygments模块，加亮显示程序代码 • 支持多种扩展功能，比如：搜索，模板定制等等

5. 文档编排方法 • 编写多个文本文件，通过使用 toctree 标记，组成整个文档 • 例如：主文件叫做 index.txt，有三个章，当前目录下分别对应文件ch1.txt，ch2.txt，ch3.txt，那么在 index.txt 中加入以下字符，即可显示章节目录： .. toctree:: :numbered: ch1 ch2 ch3

6. 内容编写方法 • 采用扩展的 reStructuredText 标记实现，基本上只要按照普通的文本文件编写方式即可。 • 段落之间用空行分开 • 斜体：*text* ，粗体：**text** ，引用：``text`` • 列表： 空格加上 * 号，或数字符号 • 源代码： 两个冒号，空行分隔缩进 • 链接： `Link text <http://target>`_ • 章节标题： 标题下边加上等长的 # * = - 等符号 • 图片： .. image:: gnu.png • 更多方法，请参考主页文档

7. 例子 程序的基本概念 ============== 程序和编程语言 -------------- 程序（Program）是一个精确说明如何进行计算的指令序列。 .. image:: intro.compile.png 自然语言和形式语言 ------------------ **自然语言** 就是人类讲的语言，比如汉语、英语和法语。C语言例子： 例 1.1. Hello World :: #include <stdio.h> int main(void) { printf("Hello, world.\n"); return 0; }

8. 软件安装和运行 • 方法一：easy_install sphinx • 方法二：Windows 用户下载 http://www.baow.com/soft/baow.zip，其中打包了 Python2.6和例子，只要解压缩到c盘目录下就行了 • 配置文件： conf.py • 例子运行命令：build.bat sphinx-build -b html linux_c_src linux_c_html

9. 实际演示

10. 高级技巧 • 演示结合Firefox 和 VIM 编写文档 • 生成文档 • VIM 支持 reStructuredText 文本的加亮显示，建议用VIM编辑器编辑

11. 结 束 杜文山 du@baow.com