写文档一向是个苦差事，但只有写出好的文档，才能有资格霸气十足的对别人淡淡道出:RTFD(Read the Fuck Document)。为了这一崇高目标，经过一些比较和调查，最终锁定Sphinx + ReadTheDocs作为文档写作工具，以下逐一道来：

---

• 使用Sphinx生成文档
  • Sphinx安装
  • Sphinx生成文档
  • Hello World
• 托管到Read the Docs

使用Sphinx生成文档

Sphinx是一个基于Python的文档生成项目。最早只是用来生成Python的项目文档，但随着这个项目的逐渐完善，很多非Python的知名项目也采用Sphinx作为文档写作工具，甚至完全可以用Sphinx来写书。

引用一段Sphinx生成文档的优点包括：

• 丰富的输出格式: 支持输出为HTML，LaTeX (可转换为PDF)， manual pages(man), 纯文本等若干种格式
• 完备的交叉引用: 语义化的标签,并对 函式,类,引文,术语以及类似片段消息可以自动化链接
• 明晰的分层结构: 轻松定义文档树,并自动化链接同级/父级/下级文章
• 美观的自动索引: 可自动生成美观的模块索引
• 精确的语法高亮: 基于 Pygments 自动生成语法高亮
• 开放的扩展: 支持代码块的自动测试,自动包含Python 的模块自述文档,等等

其实上面这么多功能，最本质的核心还是在于Sphinx采用了轻量级标记语言中的reStructuredText作为文档写作语言。reStructuredText是类似Wiki，Markdown的一种纯文本标记语言，所有Sphinx的文档其实都是扩展名为rst的纯文本文件，然后经过转换器转换为各种输出格式，并且可以配合版本控制系统轻松实现Diff。

Sphinx安装

首先安装好Python环境，建议选择Pyhon2.7.3,并且把Python及Python/Scripts目录加入环境变量，然后只需要一行命令即可

easy_install -U Sphinx

安装完毕之后，进入任意目录，运行

sphinx-quickstart

会进入一个设置向导，根据向导一步一步设置文档项目，其实必填项只有项目名称，作者和版本，其他设置都可以一路回车：

1. 文档根目录(Root path for the documentation)，默认为当前目录(.)
2. 是否分离文档源代码与生成后的文档(Separate source and build directories): y
3. 模板与静态文件存放目录前缀(Name prefix for templates and static dir):_
4. 项目名称(Project name) : EvaEngine
5. 作者名称(Author name)：AlloVince
6. 项目版本(Project version) : 1.0.1
7. 文档默认扩展名(Source file suffix) : .rst
8. 默认首页文件名(Name of your master document):index
9. 是否添加epub目录(Do you want to use the epub builder):n
10. 启用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode：n
11. 生成Makefile (Create Makefile)：y
12. 生成windows用命令行(Create Windows command file):y

最后会生成Sphinx一个文档项目必需的核心文件，包括：

readthedocs
│ make.bat
│ Makefile
├─build
└─source
　　│ conf.py
　　│ index.rst
　　├─_static
　　└─_templates

如果向导中的所有设置都保存在conf.py中，可以随时调整。

Sphinx生成文档

source目录就是存放文档源代码的目录，默认的索引页面为index.rst

我们尝试来写作第一篇文档，在source目录下建立helloworld.rst，内容为：

Hello World

同时编辑index.rst对应部分为

.. toctree::
   :maxdepth: 1

   helloworld

然后在当前目录下运行

make html

会看到build目录下会生成HTML格式的文档。同理我们可以make letex生成LeTex以及其他格式。

托管到Read the Docs

Read the Docs是一个基于Sphinx的在线文档托管系统，接受一个Git Repository或SVN仓库作为文档来源。

我们将刚才的文档项目首先托管到Github上,因为build目录下的内容是自动生成的，所以还需要写一个.gitignore将其忽略掉。

然后注册Read the Docs，在Dashboard中创建一个新的Project，Repo中填入项目的git url。

剩下的一切就交给Read the Docs吧。

我尝试创建的EvaEngine Documentation，对应的在线文档在此。

简单的流程就是这样，剩下的仍然是RTFD。

Markdown 是一种轻量级的「标记语言」，它的优点很多，目前也被越来越多的写作爱好者，撰稿者广泛使用。看到这里请不要被「标记」、「语言」所迷惑，Markdown 的语法十分简单。常用的标记符号也不超过十个，这种相对于更为复杂的HTML 标记语言来说，Markdown 可谓是十分轻量的，学习成本也不需要太多，且一旦熟悉这种语法规则，会有一劳永逸的效果。

---

• 一、认识 Markdown
  • Markdown 官方文档
  • 使用 Markdown 的优点
  • 我该用什么工具？
    • Mac 平台
    • Windows、iOS、Web 平台
• 二、Markdown 语法的简要规则
  • 标题
  • 列表
  • 引用
  • 图片与链接
  • 粗体与斜体
  • 表格
  • 代码框
  • 分割线
  • 小结
• 三、与 Markdown 相关的一些推荐
  • 可配套使用的工具
  • 相关文章阅读

一、认识 Markdown

在刚才的导语里提到，Markdown 是一种用来写作的轻量级「标记语言」，它用简洁的语法代替排版，而不像一般我们用的字处理软件 Word 或 Pages 有大量的排版、字体设置。它使我们专心于码字，用「标记」语法，来代替常见的排版格式。例如此文从内容到格式，甚至插图，键盘就可以通通搞定了。目前来看，支持 Markdown 语法的编辑器有很多，包括很多网站（例如简书）也支持了 Markdown 的文字录入。Markdown 从写作到完成，导出格式随心所欲，你可以导出 HTML 格式的文件用来网站发布，也可以十分方便的导出 PDF 格式，这种格式写出的简历更能得到 HR 的好感。甚至可以利用 CloudApp 这种云服务工具直接上传至网页用来分享你的文章，全球最大的轻博客平台 Tumblr，也支持使用 Mou 这类 Markdown 工具进行编辑并直接上传。

Markdown 官方文档

这里可以看到官方的 Markdown 语法规则文档，当然，后文我也会用自己的方式，阐述这些语法在实际使用中的用法。

• 创始人 John Gruber 的 Markdown 语法说明
• Markdown 中文版语法说明

使用 Markdown 的优点

• 专注你的文字内容而不是排版样式。
• 轻松的导出 HTML、PDF 和本身的 .md 文件。
• 纯文本内容，兼容所有的文本编辑器与字处理软件。
• 可读，直观。适合所有人的写作语言。

我该用什么工具？

Mac 平台

• 在 Mac OS X 上，我强烈建议你用 Mou 这款免费且十分好用的 Markdown 编辑器，它支持实时预览，既左边是你编辑 Markdown 语言，右边会实时的生成预览效果，笔者文章就是 Mou 这款应用写出来的。

其次还有很多同类选择。如果你是个编辑作者，我强烈建议你购买 Ulysses Ⅲ，这款应用入围了苹果去年 Mac App Store 的 The Best of 2013，相比 Mou 它支持更多的写作格式、多文档的支持。Mou、iA Writer 这些应用都是基于单文档的管理方式，而 Ulysses Ⅲ 支持 Folder、Filter 的管理，一个 Folder 里面可以创建多个 Sheet，Sheet 之间还可以进行 Combine 处理。

Windows、iOS、Web 平台

• 笔者并未使用过 Windows 下的 Markdown 工具，但经朋友介绍，有两款还算不错，一款叫 MarkdownPad ，另一款叫 MarkPad。

• iOS 端已有相当多的 app 支持 Markdown 语法编辑，例如 Drafts、Day One、iA Writer 等。

• Web 端上，我强烈推荐 简书 这款产品，上面有无数热爱文字的人在不停的创造、分享。在 Web 端使用 Markdown 没有比简书更舒服的地方了，它同样支持左右两栏的实时预览，字体优雅、简洁。

• 同样是 Web 端，Draftin 这款在线 MD 编辑器也近乎完美。
• Web 端, 也可以试下StackEdit – In-browser markdown editor
  Chrome 浏览器的有它的应用StackEdit,那样就可以离线用了。本文就是使用这个工具编辑的。

二、Markdown 语法的简要规则

标题

标题是每篇文章都需要也是最常用的格式，在 Markdown 中，如果一段文字被定义为标题，只要在这段文字前加 # 号即可。

# 一级标题

## 二级标题

### 三级标题

以此类推，总共六级标题，建议在井号后加一个空格，这是最标准的 Markdown 语法。

列表

熟悉 HTML 的同学肯定知道有序列表与无序列表的区别，在 Markdown 下，列表的显示只需要在文字前加上 - 或 * 即可变为无序列表，有序列表则直接在文字前加 1.``2.``3. 符号要和文字之间加上一个字符的空格。

引用

如果你需要引用一小段别处的句子，那么就要用引用的格式。

> 例如这样

只需要在文本前加入 > 这种尖括号（大于号）即可

图片与链接

插入链接与插入图片的语法很像，区别在一个 !号

插入图片的地址需要图床，这里推荐 CloudApp 的服务，生成URL地址即可。

粗体与斜体

Markdown 的粗体和斜体也非常简单，用两个 * 包含一段文本就是粗体的语法，用一个 * 包含一段文本就是斜体的语法。

例如：这里是粗体这里是斜体

表格

表格是我觉得 Markdown 比较累人的地方，例子如下：

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

代码框

如果你是个程序猿，需要在文章里优雅的引用代码框，在 Markdown 下实现也非常简单，只需要用两个 ` 把中间的代码包裹起来，如 code。图例：

使用 tab 键即可缩进。

分割线

分割线的语法只需要另起一行，连续输入三个星号 *** 即可。

小结

到这里，Markdown 的基本语法在日常的使用中基本就没什么大问题了，只要多加练习，配合好用的工具，写起东西来肯定会行云流水。更多的语法规则，其实 Mou 的 Help 文档例子很好，当你第一次使用 Mou 时，就会显示该文档，其次，你也可在撰写过程中，使用 CMD+R 快捷键来快速打开文档，以随时查阅和学习语法。

三、与 Markdown 相关的一些推荐

可配套使用的工具

• Droplr
• Cloudapp
• ezShare for Mac
• 围脖图床修复计划
• 马克飞象，专为印象笔记打造的 Markdown 编辑器，非常推荐

相关文章阅读

• 为什么作家应该用 Markdown 保存自己的文稿
• Markdown 写作浅谈
• Markdown 工具补完
• Drafts + Scriptogr.am + Dropbox 打造移动端 Markdown 风格博客
• 图灵社区 - 怎样使用 Markdown
• 为什么我们要学习 Markdown 的三个理由
• Markdown 语法写作入门指南 by ibuick

Hexo提供了诸多插件来增强博客体验，地址http://hexo.io/plugins/。
在博客搬迁的时发现一个生成文章目录的插件，hexo-toc。

---

hexo-toc

为防插件误认标记，文章以下出现的 ttoc 实际为 toc。

使用方法跟显示文章摘要类似，在Markdown中需要显示文章目录的地方添加 <!-- ttoc -->。

安装

npm install hexo-toc --save

配置

在博客根目录下的 _config.yml 中如下配置：

toc:
  maxDepth: 3

maxDepth 表示目录深度为3，即最多生成三级目录。

好了，现在重启Hexo预览下效果吧。