Sphinx
==================

.. image:: ../_static/sphinx.png

概述
----
Sphinx 是种令人可以轻松撰写出明智/优美的文档工具, 由 Georg Brandl 在BSD 许可证下创造.

Sphinx 已在支持是 `the 新版Python <http://docs.python.org>`_ 文档的生成, 也成为Python项目首选的文档工具,同时也对 C/C++ 工程有很好的支持; 进一步的,也将对其它开发语言进行特殊支持. 

Sphnix还在继续开发. 下列特性工作良好,并在Python官方文档中有“体现”:

- 丰富的输出格式: HTML (包括M$帮助), LaTeX (为PDF输出), manual pages(man), 纯文本
- 完备的交叉引用: 语义化的标签,并对 函式,类,引文,术语以及类似片段消息可以自动化链接
- 明晰的分层结构: 轻松定义文档树,并自动化链接同级/父级/下级文章
- 美观的自动索引: 可自动生成美观的模块索引
- 精确的语法高亮: 基于 Pygments 自动生成语法高亮
- 开放的扩展: 支持代码块的自动测试,自动包含Python 的模块自述文档,等等
- Sphinx 使用新结构化文本 作为标记语言,因而直接享受了来自Docutils 为 reStructuredText 提供的多种工具和能力!

安装
-----

解决依赖关系

- Python 2.x (http://www.python.org/), 并将 Python 加入到 Path 中;
- Setup Tools: Python 的一个包安装/管理工具(http://pypi.python.org/pypi/setuptools, win 下有 exe, 直接安装即可);
- 安装 docutils, cmd 下进入 kissyteam/tools/docutils-0.7, 运行 ``python setup.py install``;

安装 Sphinx

- cmd 下运行: ``easy_install -U Sphinx``;
- cmd 下进入 kissyteam/tools/sphinx-to-github, 运行 ``python setup.py install``;


配置
-----

使用
-----
编译文档

- cmd 进入 kissyteam 目录, 运行 ``make html`` (msdos下运行 ``make.bat html``  , 在 _build 下生成 html;
- 如果你想进一步了解如何创建 sphinx 工程, 见 http://code.google.com/p/pymotwcn/wiki/SphinxprojectHowto ;

模板修改
--------

配置文件为 ``conf.py`` ，在其中找到 ``html_theme = 'default'`` 这一段，基中“default”即为模板名称。Sphinx提供七种模板候选，名称为别为：

- default
- sphinxdoc
- scrolls
- agogo
- traditional
- nature
- haiku

修改模板，只需将上面提到的 ``default`` 换成后面相应的六种名称即可。效果图，请移步这里：

http://sphinx.pocoo.org/theming.html