莊周夢蝶

    繼續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，具體使用請看他們的文檔。