庄周梦蝶

    继续Clojure世界之旅，介绍下我今天的探索成果，使用clojure生成clojure项目的API文档。在java里，我们是利用javadoc生成API文档，各种build工具都提供了集成，例如maven和ant都提供了javadoc插件或者task。在Clojure世界里，同样有一系列工具帮助你从源码中自动化生成API文档。今天主要介绍三个工具。不过我不会介绍怎么在clojure里写doc，具体怎么做请看一些开源项目，或者直接看clojure.core的源码。

    首先是codox，使用相当简单，我们这里都假设你使用Leiningen作为构建工具，在project.clj里添加codox依赖：

    解下执行lein doc命令即可生成文档，生成的文档放在doc目录，在浏览器里打开index.html即可观察生成的文档。我给clojure-control生成的codox文档可以看这个链接，效果还是不错的。

    第二个要介绍的工具是marginalia，使用方法类似codox，首先还是添加依赖：
   
    执行lein deps处理依赖关系，然后执行lein marg命令即可在docs目录生成文档，与codox不同的是marginalia只生成一个html文件，没有带js和css，但是效果也不错，可以看我给clojure-control生成的marg文档链接。marginalia生成的文档说明和源码左右对照，很利于阅读源码。

   最后要介绍的就是Clojure.org自己在使用的autodoc，如果你喜欢clojure.org上的API文档格式可以采用这个工具。并且autodoc可以跟github pages结合起来，生成完整的项目文档并展示在github上。例如以clojure-control为例来介绍整个过程。首先你需要配置你的github pages，参照这个链接http://pages.github.com/。

    第一步，仍然是在project.clj添加依赖：
       第二步，在你的.gitignore里忽略autodoc目录：
       将这些更改提交到github上，接下来在你的项目目录clone一份项目源码到<project>/autodoc目录：
       进入autodoc目录，执行下列命令创建一个gh-pages分支：
     回到项目根目录后，执行lein autodoc命令在autodoc目录生成文档：
     接下来将生成的文档推送到github分支上：
    等上几分钟，让github渲染你的文档，最终的效果看这个链接 http://killme2008.github.com/clojure-control     
    autodoc和marginalia都支持maven，具体使用请看他们的文档。