手把手教你Sphinx（二）——制作一份学习研讨会报告

1. 创建项目

在目标目录下执行sphinx-quickstart命令，创建一个名为report的项目文档，除了以下配置项外，其余均取默认值即可：

$ sphinx-quickstart report
> Project name: Sphinx学习研讨会报告
> Author name(s): hymanlu
> Project version []: 1.0.0
> Project release [1.0.0]:
> Project language [en]: zh_CN

这次的项目演示由于不需要用到原来默认的index.rst文件内容，直接清空即可。

2. 编写标题

首先就是编写文档标题：

====================
Sphinx学习研讨会报告
====================

就像上面那样，在文字的上下都加上相同长度的=序列，就成了一个标题段落。注意：=序列的长度只能长于字符串而不能短于。

编辑完index.rst后直接保存，然后再使用make html或者./make.bat html命令就能将我们的文档编译成网页文件了。

生成的网页文件就位于_build/html/index.html，使用浏览器打开后的效果为：

3. 编写其他段落

====================
Sphinx学习研讨会报告
====================

概要信息
========

研讨会的内容
============

资料
====

4. 添加概要信息

接下来，就让我们往概要信息中逐条添加与会者、时间、地点等信息

概要信息
========
* 时间： 2013/12/21 13:00-17:00
* 地点： CoCoDe
* 与会者： planset, ...

在*、+、-之后加一个空格，代表的就是一个列表项（无序），编译后生成的就是我们所熟悉的<ul><li>等html标签；

如果你想创建有序列表，则应当像下面这么写：

1. 项目1
2. 项目2
3. 项目3

编译后生成的就是我们所熟悉的<ol><li>等html标签

5. 添加研讨会的内容

当要编写一长段文字时，应当考虑进行段落划分，此时只需在合适的地方加入一个空行即可：

研讨会的内容
============
最近参加了一个Sphinx学习研讨会。

以下是关于Sphinx的一些总结：

    所谓Sphinx，其实就是一个能将reStructuredText语法的文本文件转换为HTML、PDF、epub等格式的强大工具。

    Python的官方文档就是利用这款工具书写而成的，并且被广泛用于各式各样的说明文档。

在该研讨会里，我们一边编写学习报告一边学习Sphinx相关知识。

正如上面文档所示，在行开头加入数个空格，则表示该行的内容为外部引用，会在编译后变成我们所熟悉的<blockquote>html标签

6. 添加资料链接

资料
====

* http://sphinx-doc.org/
* `github <https://github.com>`_
* Sphinx中文指南_

.. _Sphinx中文指南: http://www.sphinxsearch.org/sphinx-tutorial

上面展示了3种编写外部超链接的方法：

直接写完整的URL，会自动转化为对应的超链接；
链接名称链接URL_
链接名称_ 然后在末尾补充其对应的链接URL，写法为.. _链接名称: 链接URL