用 Markdown 来给开源项目写文档

  • Post author:
  • Post category:IT
  • Post comments:0评论

良好和专业的文档对于一个开源软件项目来说, 其重要程度和软件的功能不相上下. 项目有了良好的文档, 体现出专业程度, 用户便会放心试用软件, 从而成为真正的用户.

对于一个开源软件项目来说, 文档一般是指 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 文件.

Related posts:

  1. 使用 DocBook 编写书籍和文档
  2. SSDB 现在已经支持 Java 语言了!
  3. 用C语法来写Python代码
  4. Cpy是如何打败Python的
  5. PyPy – 吞下自己尾巴的小蟒蛇

发表评论