文档

• 函数/类的接口说明文档， 比如 XXX Framework API Documentation
• 服务端接口说明文档，比如 Web Service API, Restful API 等
• 使用指南、手册等说明文档，比如 Getting Start XXX, XXX Tutorial, XXX Guideline, XXX Manual 等
• 设计相关文档，比如 数据库 ER 图、类图、时序图等（Enterprise Architect）

下面，我们将分别介绍一些常用的相关工具/平台

此类文档内容多以大段文字说明为主，一般按章节进行内容组织，随着项目的不断成熟、演进，很多成熟项目的文档都会有相当篇幅；于此同时，出于格式、排版等需求，逐步形成了多种标记语言标准，常见的比如 TeX, DocBook, Markdown, reStructuredText, AsciiDoc 等。目前互联网项目中主要流行 Markdown, reStructuredText, AsciiDoc 等轻量级标记语言，Tex、DocBook 过于复杂，reStructuredText 主要在 Python 开发者中流行，Org-mode 主要以 Emacs 用户为主，Markdown 最为流行（由于 Markdown 过于简单，目前几大组织/公司分别定义了自己的 Markdown 扩展语法，比如 GitHub Flavored Markdown，MultiMarkdown，Markdown Extra，Pandoc Markdown 等）。

• Comparison of document markup languages
• - 其中有好几种都是 Markdown 的方言；毛主席教导我们要辩证的去看问题，多种方言同时出现一方面反映出以简为美起家的 Markdown 是如此流行，另一方面也显示出 Markdown 扩展语法标准混乱的无奈。
• Lightweight Markup: Markdown, reStructuredText, MediaWiki, AsciiDoc, Org-mode

ReST（reStructuredText）

Markdown

由于 简单易读，只需要普通的文本编辑器就能够编辑，语法更是简单到每个人都可以在数分钟内学会，因此，作为一门 2004 年才被发明出来的轻量级标记语言，Markdown 很快便得到了诸如 Github，, Stack Exchange, 等大量网站的支持。而伴随着 Github 旋风横扫整个开源界， git + Github + Markdown + Jekyll 组合更是成为互联网时代大量科技写作者甚至小部分文艺青年的主力生产力平台。

• Jekyll - 不仅仅可以生成静态博客站点，Jekyll 同样适用于文档内容生成，Wista（一家企业视频托管服务提供商）分享了他们基于 Jekyll 的文档管理经验，你可以点这里先睹为快（）。下面列举了 Jekyll 文档其他相关主题，
  • Jekyll Documentation Theme，示例：
  • Jekyll-docs-template，示例：，ModelTree
• - 根据 Markdown 文档生成静态网站，Python 语言开发，
  • SlimFramework v2 Doc - 个人常用的一个 PHP 轻量级框架，小内核 + Composer 包，可玩性很高~ 类似的可选项还有 和 Lumen
  • Flask API Doc - 另外一款轻量级 Python Web 开发框架
• - 除了 Markdown，GitBook 还支持另外一种与 Markdown 很类似但功能更丰富的标记语言 AsciiDoc；GitBook 除了提供基于 node.js 开发的可供本地运行的命令行版本外，还提供了在线托管服务。
• Peach - 国人基于 Go 语言开发的一款支持多语言、实时同步以及全文搜索功能的 Web 文档服务器。赞一个~，使用示例，
  • - Peach 官方文档
  • Gogs 文档 - 国人基于 Go 语言开发的类 Gitlab 服务器，界面比较小清新哦~

下面的表格对比了几款支持 Markdown 的主流文档工具之间主要特性的区别（实际区别可能与我所理解的有偏差）：

AsciiDoc

扩展阅读：

• AsciiDoctor - 2013 年发布，是 AsciiDoc 基于 Ruby 语言的实现，主要。

DocBook

• 比 HTML 语言还早一年（1992 年）出现的 XML 系标记语言，可以非常方便的生成其他文件格式，比如 HTMl、PDF、CHM 等，开源界使用 DocBook 的项目非常多，比如大家耳熟能详的一些项目，Linux Kernel、、PostgreSQL、、OpenStack，也用的它哦，更多项目和组织列表可以看这里；不过纯 PHP 相关项目使用 Docbook 的较少，毕竟使用 XML 来写文档门槛有点高 ，项目示例，
  • ，源码

Tex

Tex 是由 创造的基于低级编程语言的电子排版系统，利用 TeX 能够对文章进行十分精美的排版，TeX 提供了一套功能强大并且十分灵活的排版语言，同时 TeX 系统是公认的数学公式排得最好的系统。

• PHPDoc，写 PHP 的都应该知道这个哈，嘿嘿。示例，
  • Offical Demo with Clean2 theme
• ，Symfony 框架使用的文档生成工具，示例，
  • Symfony 3.0 API
• Doxygen，超级老牌文档生成工具了，除了 PHP 外还支持其他 N 种编程语言
• Apigen
  • CakePHP API Docs

• , Demo
• - （推荐）Apiary.io平台具有协同设计、即时API模拟、快速生成源码、自动测试和代码调试的开源设计工具，最重要的是可以在线模拟测试，因为该平台具备模拟服务器测试服务，可以把设计好的程序在线测试、验证。
• Apidoc,
• Slate - 创建好看的 API 文档，Travis-CI, Appium 等项目使用中，更多例子：
• JSON-Schema
• - JSON Schema tools and doc generation for HTTP APIs