315
汽車大全
Clojure世界：API文檔生成
繼續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，參照這個鏈接https://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目錄生成文檔：$ git symbolic-ref HEAD refs/heads/gh-pages
$ rm .git/index
$ git clean -fdx
$ cd ..
lein autodoc
接下來將生成的文檔推送到github分支上： $cd autodoc
$ git add -A
$ git commit -m"Documentation update"
$ git push origin gh-pages
$ git add -A
$ git commit -m"Documentation update"
$ git push origin gh-pages
等上幾分鍾，讓github渲染你的文檔，最終的效果看這個鏈接 https://killme2008.github.com/clojure-control
autodoc和marginalia都支持maven，具體使用請看他們的文檔。
文章轉自莊周夢蝶 ，原文發布時間
最後更新：2017-05-18 20:36:21