+++++++++++++++++++++++++++++++++++++++++
文档工具 Sphinx 
+++++++++++++++++++++++++++++++++++++++++
本节主要介绍Python文档生成器Sphinx,在介绍一些Sphinx命令。

Sphinx简介
===================================
`Sphinx <http://sphinx.pocoo.org/index.html>`_ 是由 *Georg Brandl* 开发的python文档生成器，它可以将一系列的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 源文件转换成各种输出格式，并且自动生成交叉引用，索引等。也支持C/C++语言，将计划支持更多的语言。

Sphinx可以生成的文档类型：HTML、htmlhelp/chm、qthelp、devhelp、LaTex、man、PDF等，而且很方便浏览和导航。



如何使用Sphinx
========================================
**1. 配置工作环境:**

    建立工作根目录，假设命名为docs，在其中配置一个包含 ``conf.py`` 文件的工作环境，这样就可以配置Sphinx读取文件的方式以及如何建立文档。只需运行Sphinx的命令 **sphinx-quickstart** ，并回答运行程序提出的问题。

    ::
   
          $ cd path/
          $ mkdir docs
          $ cd docs  
          $ sphinx-quickstart
 
    另外，Sphinx有一个"API文档"自动生成器 `sphinx apidoc <http://sphinx.pocoo.org/invocation.html#invocation-apidoc>`_.

**2. 定义文件结构:**

    正确运行 **sphinx-quickstart** 之后，会配置好 ``conf.py`` 文件，同时也会生成一个 ``index.rst`` 文件（如果默认情况下），我们可以在它里面定义新的目录树结构。

    刚初始化的空目录树结构是如下的代码::

        .. toctree::
           :maxdepth: 2

    可以在其下面列出要添加的目录结构，比如添加sphinx和reStructuredText::

        .. toctree::
           :maxdepth: 2
       
           sphinx
           reStructuredText
    
    关于toctree如何定义等其他内容参考 `The TOC tree <http://sphinx.pocoo.org/markup/toctree.html#toctree-directive>`_.

**3.添加目录文件:**
  
    定义好toctree之后就要添加目录文件，也就是目录索引的内容，书写的语法规则可以学习 `reStruturedText <reStructuredText>`_.

**4.最后的组装:**
   
    到此为止，离生成最后的文档就只有一步之遥了，可以运行 **sphinx-build** 程序来完成组装，以生成HTML文档为例::
    
        $ sphinx-build -b html sourcedir   builddir

    其中 *sourcedir* 是之前创建的根目录，也就算 *docs* 目录， *builddir* 是将要存放html文档的目录，*-b* 选项是指选择一个编译器。 
    
    另外，**sphinx-quickstare** 同时还创建了 ``Makefile`` 和 ``make.bat`` 文件，还可以运行如下命令组装HTML文档::
  
         $ make html
    
    生成其他文档格式，比如pdf格式，可以运行 ``make latexpdf`` 调用LaTex编译器，Sphinx各种编译器可以参考 `Sphinx builders <http://sphinx.pocoo.org/builders.html#module-sphinx.builders>`.

参考资料
==================
Sphinx 学习手册:  http://sphinx.pocoo.org/index.html

Sphinx 下载: http://pypi.python.org/pypi/Sphinx

Read the Docs手册: http://read-the-docs.readthedocs.org/en/latest/getting_started.html