两个文档生成工具：phpDocumentor和Sphinx

一、phpDocumentor

phpDocumentor是针对PHP的文档自动生成工具。官方网站在：http://www.phpdoc.org/

github地址：

https://github.com/phpDocumentor/phpDocumentor2

在linux下可以通过pear工具安装：

$ sudo apt-get install php5-xsl
$ pear channel-discover pear.phpdoc.org
$ pear install phpdoc/phpDocumentor-alpha

安装完后就可以直接用phpdoc命令行来生成文档：

$ phpdoc -d [SOURCE_PATH] -t [TARGET_PATH]

其中SOURCE_PATH为php项目的目录地址，TARGET_PATH为生成后的文档目录。例如：

$ pwd
/home/chenming/www/email_importer
$ phpdoc run -d . -t doc

生成好后，直接在doc目录下找index.html打开就可以看到文档了。
更详细的用法参见官方文档。

二、Sphinx

Sphinx是一个reStructuredText格式的文档自动生成工具，python和django等的官方文档就是用的它。

官方网站：http://sphinx.pocoo.org/ PS.这个工具与一个分词索引的工具名字一样的，支持中文的sphinx叫coreseek。

通过python的easy_install工具安装：

sudo easy_install sphinx

安装好后，通过如下命令快速开始：

$ sphinx-quickstart

这个命令类似于一个新建文档的向导，基本上默认下去就可以了。完成后的目录结构：

.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst

其中conf.py：这是一个 Python 文件，用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart 时选中的那些值。可以在里面修改一些参数，如主题设置：

html_theme_path = ['_themes']  #主题目录
html_theme = 'nature'          #主题名称

可以在google里面搜索些主题，”sphinx theme”，下载主题后把主题文件夹放到项目文件夹下面的_themes(我们上面配置的)文件夹下面就可以了。

sphinx采用的reStructuredText格式，具体的文档编写格式就得看官网的文档了，写得比较详细。还有就是可以查看别人的文档源码来学习，比如phpDocumentor和sphinx官方网站的文档，每个页面都会有一个“Show Source”的按钮，点击就可以查看源码文档。

reStructuredText详细格式文档：

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

编写完sphinx文档后，生成html的命令：

make html

然后就可以到生成好的目录下面打开漂亮的文档页面啦。而且还可以方便地更改主题，甚至定制自己的主题。

代码高亮设置，先安装pygments：

sudo apt-get install python-pygments
#或
sudo easy_install Pygments

然后在文档结构里面这样写：

.. highlight:: bash

.. code-block:: bash

    #!/bin/bash
    #encoding=utf-8
    #下面写代码

设置颜色主题在conf.py中设置：

# The name of the Pygments (syntax highlighting) style to use.
#pygments_style = 'sphinx'
pygments_style = 'perldoc'
#http://pygments.org/demo/

有了这两个工具，写文档就高效多了，基本上只关心文字的东西，不用担心文档格式与结构的组织。

后记：在vim中有一个插件叫vimwiki

https://github.com/vim-scripts/vimwiki

可以用来作本地wiki的工具，与vim集成，支持生成html等格式。

Kyle's Blog