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