Clojure世界:API文档生成
2023-03-14 22:30:44 时间
继续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添加依赖:
首先是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目录生成文档:$ 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渲染你的文档,最终的效果看这个链接 http://killme2008.github.com/clojure-control
autodoc和marginalia都支持maven,具体使用请看他们的文档。
文章转自庄周梦蝶 ,原文发布时间 2012-03-21
相关文章
- 在 Go 里用 CGO?这 7 个问题你要关注!
- 9款优秀的去中心化通讯软件 Matrix 的客户端
- 求职数据分析,项目经验该怎么写
- 在OKR中,我看到了数据驱动业务的未来
- 火山引擎云原生大数据在金融行业的实践
- OpenHarmony富设备移植指南(二)—从postmarketOS获取移植资源
- 《数据成熟度指数》报告:64%的企业领袖认为大多数员工“不懂数据”
- OpenHarmony 小型系统兼容性测试指南
- 肯睿中国(Cloudera):2023年企业数字战略三大趋势预测
- 适用于 Linux 的十大命令行游戏
- GNOME 截图工具的新旧截图方式
- System76 即将推出的 COSMIC 桌面正在酝酿大变化
- 2GB 内存 8GB 存储即可流畅运行,Windows 11 极致精简版系统 Tiny11 发布
- 迎接 ecode:一个即将推出的具有全新图形用户界面框架的现代、轻量级代码编辑器
- loongarch架构介绍(三)—地址翻译
- Go 语言怎么解决编译器错误“err is shadowed during return”?
- 敏捷:可能被开发人员遗忘的部分
- Denodo预测2023年数据管理和分析的未来
- 利用数据推动可持续发展
- 在 Vue3 中实现 React 原生 Hooks(useState、useEffect),深入理解 React Hooks 的