继续Clojure世界之旅，介绍下我今天的探索成果，使用clojure生成clojure项目的API文档。在java里，我们是利用javadoc生成API文档，各种build工具都提供了集成，例如maven和ant都提供了javadoc插件或者task。在Clojure世界里，同样有一系列工具帮助你从源码中自动化生成API文档。今天主要介绍三个工具。不过我不会介绍怎么在clojure里写doc，具体怎么做请看一些开源项目，或者直接看clojure.core的源码。
首先是codox，使用相当简单，我们这里都假设你使用Leiningen作为构建工具，在project.clj里添加codox依赖：
:dev-dependencies [[codox "0.5.0"]]
解下执行lein doc命令即可生成文档，生成的文档放在doc目录，在浏览器里打开index.html即可观察生成的文档。我给clojure-control生成的codox文档可以看这个链接，效果还是不错的。
第二个要介绍的工具是marginalia，使用方法类似codox，首先还是添加依赖：
:dev-dependencies [lein-marginalia "0.7.0"]
执行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添加依赖：
:dev-dependencies [[lein-autodoc "0.9.0"]]
第二步，在你的.gitignore里忽略autodoc目录：
autodoc/**
将这些更改提交到github上，接下来在你的项目目录clone一份项目源码到<project>/autodoc目录：
git clone git@github.com:<user name>/<project name>.git autodoc
进入autodoc目录，执行下列命令创建一个gh-pages分支：
$ cd autodoc
$ git symbolic-ref HEAD refs/heads/gh-pages
$ rm .git/index
$ git clean -fdx
$ cd ..
回到项目根目录后，执行lein autodoc命令在autodoc目录生成文档：
lein autodoc
接下来将生成的文档推送到github分支上：
$cd autodoc
$ git add -A
$ git commit -m"Documentation update"
$ git push origin gh-pages
等上几分钟，让github渲染你的文档，最终的效果看这个链接 http://killme2008.github.com/clojure-control
autodoc和marginalia都支持maven，具体使用请看他们的文档。
文章转自庄周梦蝶 ，原文发布时间 2012-03-21