良好和专业的文档对于一个开源软件项目来说, 其重要程度和软件的功能不相上下. 项目有了良好的文档, 体现出专业程度, 用户便会放心试用软件, 从而成为真正的用户.
对于一个开源软件项目来说, 文档一般是指 API 文档, 配置帮助文档, 用户手册(Manual), 教程(Tutorial), 设计思路等等. 那么, 用什么工具来编写文档呢? 其实, 不同项目使用的工具各不相同, 比较常用的工具是 Doxygen, Docbook. 这两个工具我都用过, 说实话, 我没掌握它们的精髓, 使用起来不是很爽.
Doxygen 主要用来从代码注释中提取生成 API 文档, 但说实话, 默认的模板十分难看, 生成的文档不知所云, 比 Javadoc 生成的文档的清晰度差远了, 我无法理解它的文档组织结构的优点. Doxygen 也能生成 API 文档之外的其它类型的文档.
我曾经用 Docbook 写过一个教程, 有点想写书, 是用 XML 写的, 生成的文档也是有章节的那种, 但不太适合用来编写以篇为单位的那种文档.
最终, 我采用了 Markdown (格式和工具) 来给 SSDB 数据库项目编写文档, 并使用 bootstrap 来做界面美化. 以前我便使用 Markdown 格式来写了一些文章, 但 SSDB 的文档完全采用 Markdown 来编写, 是受了 beego 项目的启发. Beego 的项目文档, 是我见过了国内开源项目中最专业化和最美观的项目之一.
Beego 采用 Markdown 格式编写文章, 然后用一个 Go 语言的工具实时生成 HTML 网页. 我的服务器还没有用 Go 语言, 所以找了一个 Python 的 Markdown 解析库(Python Markdown), 然后用 PHP 做了包装, 做成一个文档生成工具. 之所以使用 PHP, 是因为 PHP 本身是一个模板语言, 同时也有丰富的函数, 处理文本文件非常方便.
最后做成的就是 ssdb-docs 这个 SSDB 数据库的文档项目. 大家如果感兴趣, 可以直接把这个 Markdown 文档工具拿来用, 也给自己的项目写文档. 用起来非常方便, 把你的 .md 文件放到一个目录, 就能一行命令解析并生成 HTML 文件.
greatghoul
2014-01-15 at 09:39:18
ideawu
2014-01-15 at 09:57:12
Loading ...