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

手把手教你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, ...

在*、+、-之后加一个空格，代表的就是一个列表项（无序），编译后生成的就是我们所熟悉的

• 等html标签；

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

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

  编译后生成的就是我们所熟悉的

  1. 等html标签

     5. 添加研讨会的内容

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

     研讨会的内容
     ============
     最近参加了一个Sphinx学习研讨会。
     
     以下是关于Sphinx的一些总结：
     
         所谓Sphinx，其实就是一个能将reStructuredText语法的文本文件转换为HTML、PDF、epub等格式的强大工具。
     
         Python的官方文档就是利用这款工具书写而成的，并且被广泛用于各式各样的说明文档。
     
     在该研讨会里，我们一边编写学习报告一边学习Sphinx相关知识。

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

     html标签

     6. 添加资料链接

     资料
     ====
     
     * http://sphinx-doc.org/
     * `github `_
     * Sphinx中文指南_
     
     .. _Sphinx中文指南: http://www.sphinxsearch.org/sphinx-tutorial

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

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

     7. 最终效果