6.12. Maven sphinx 插件

6.12.1. 代码和文档一样重要

好的用户使用文档可以显著减少用户接入工作，让开发人员从繁复的业务接入中解脱出来。 怎样保证文档的质量呢？–> 让文档向代码一样可以review, 这就需要文档使用纯文本你编写，而不是word或者wiki。

现在比较流行的纯文本编写文档语言有：Markdown. reStructured等. sphinx是使用reStructuredText 标记语法的文档编写工具，用户使用纯文本编写，sphinx可以自动生成各种格式的文档。

因为对sphinx更熟悉一些，因此介绍一下如何将sphinx和maven工程整合起来

6.12.2. Maven + sphinx

安装sphinx

sudo easy_install sphinx

在maven工程下初始化sphinx目录

mkdir -p src/site/sphinx
cd sr/site/sphinx
sphinx-quickstart

pom添加sphinx的构建

<build>
  <plugins>
    <plugin>
      <groupId>org.tomdz.maven</groupId>
      <artifactId>sphinx-maven-plugin</artifactId>
      <version>1.0.3</version>
      <configuration>
        <builder>html</builder>
        <outputDirectory>${project.reporting.outputDirectory}/doc</outputDirectory>
      </configuration>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

使用reStructured Text编写文档, 参见：http://sphinx-doc.org/

编译：

mvn clean packgae

输出在target/site/doc

启动http服务

cd target/site/doc
python -m SimpleHTTPServer