庄周梦蝶

生活、程序、未来
   :: 首页 ::  ::  :: 聚合  :: 管理

Clojure世界:API文档生成

Posted on 2012-03-21 22:24 dennis 阅读(3936) 评论(0)  编辑  收藏 所属分类: Clojure

    继续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,具体使用请看他们的文档。

只有注册用户登录后才能发表评论。


网站导航: