Sphinx

Sphinx 是用来生成文档的，设计的初衷是为了生成python的文档。可以生成html、htmlhelp/chm、qthelp、devhelp、latex、man 等格式的文档。

安装

easy_install -U Sphinx使用

类似于：

• qdoc3 工作时需要一个 xxx.qdocconf 文件
• doxygen 工作时需要一个 Doxyfile 文件

sphinx 工作时需要一个 conf.py 文件

运行 sphinx：

sphinx-build -b html sourcedir builddir

其中，-b 选项控制生成何种格式的文档

sphinx-quickstart

sphinx 提供有一个脚本 sphinx-quickstart，该脚本在两个方面可以简化sphinx的使用

• 该脚本可以生成 conf.py 配置文件，而不必从空白文件创建。
• 该脚本可以生成一个 Makefile 和 make.bat 文件。这样可以直接运行

make html

而不用我们直接来调用

sphinx-build -b html sourcedir builddir例子

这是 sphinx-quickstart 默认生成的 index.rst 文件：

.. Hello Sphinx documentation master file, created by
   sphinx-quickstart on Sat Oct 09 21:32:40 2010.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Hello Sphinx's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`search`

• 一开始 ..  开头的是注释

• .. toctree:: 是标示符(directive),后可跟参数、选项及内容。

• 以 ===== 标出的是章节的标题

• 以 * 开始的是列表

• :ref: 后面是交叉引用

• 此处反引号括住的 `genindex` 属于特殊名字(Special names)，不可创建该名字的文档

.. toctree::

.. toctree::
   :maxdepth: 2
   
   intro
   All about strings <strings>

包含 toctree 的称为主控文档（master document），除此之外，我们还有一系列的文档，比如intro.rst,strings.rst等，通过此处的 intro 等建立连接。