Sphinx与reStructuredText

前言

如果是Python程序员,应该对 =reStructuredText= 不会陌生,结合 =Sphinx= 工具来写文档就更加便捷;同时,写好的文档可以托管到RTD

工作流可以是这样: 在GitHub建立一个项目用于写文档,文档使用 =Sphinx结合reStructuredText= 或 =mkdocs结合Markdown= 格式,设置WebHook连接到ReadTheDocs自动更新。

Sphinx简单使用

安装工具

1
$ sudo pip install sphinx sphinx-autobuild

新建文档项目

1
2
3
$ mkdir docs
$ cd docs
$ sphinx-quickstart

生成特定格式文档

1
2
3
$ make html
$ make latexpdf
$ make epub

GitHub Webhook

  • Go to the Settings page for your project
  • Click Webhooks & Service
  • In the Services section, click Add service
  • In the list of available services, click ReadTheDocs
  • Check Active
  • Click Add service

这样设置后,一旦GitHub上的项目更新了,则会自动更新ReadTheDocs上的文档。

本地使用RTD主题

1
$ sudo pip install sphinx_rtd_theme

更新config.py:

1
2
3
4
5
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Sphinx生成pdf的中文支持问题

目前看来几个文档,如果不想认真地去学一遍Tex的话,还真没有很好地解决方法,暂时可以修改config.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
language = "zh_CN"
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '12pt',
'classoptions': ',english',
'inputenc': '',
'utf8extra': '',
# Additional stuff for the LaTeX preamble.
'preamble': '''
\usepackage{xeCJK}
\usepackage{indentfirst}
\setlength{\parindent}{2em}
\setCJKmainfont[BoldFont=SimHei, ItalicFont=STKaiti]{SimSun}
\setCJKmonofont[Scale=0.9]{Consolas}
\setCJKfamilyfont{song}[BoldFont=SimSun]{SimSun}
\setCJKfamilyfont{sf}[BoldFont=SimSun]{SimSun}
'''
}

生成pdf:

1
2
3
$ make latex
$ cd _build/latex/
$ xelatex *.tex

reStructuredText标记

注释

.. 开头的是内部注释,不会显示在结果文件中,必须以其开头,前面不可有空格.

标题

如:

1
2
3
4
標題
========================
小標題
------------------------

段落

中间空一行即可.

字体格式

1
2
3
4
5
**粗體**
*斜體*
``保持原样输出``

文字解释标记

通过 `` 来实现更多功能的标记.

连结:

1
2
3
`something`_
.. _something: www.example.com

锚标记:

1
_`something`

创建锚标记后,其他地方如果引用这个锚标记,则可以在文档内交叉引用。

通过 :sub::sup: 来支持下标与上标:

1
2
3
:sub:`下标内容`
`上标内容`:sup:

超链接

  • 第一种,直接写一个网址

  • 第二种,为文字指定一个超链接(需要的时候可以使用转义字符,用于转义空格):

1
2
3
`APEC蓝`_
.. _APEC蓝: www.example.com
  • 第三种,内嵌超链接
1
`APEC蓝<www.example.com>`_
  • 第四种,无名超链接:
1
2
3
Python is `one of the best scripting language`__ in the world.
.. __: www.example.com
  • 第五种,文件内部标题自动作为连结地址,可以建立文件内部连结:
1
`第一章`_
  • 第六种,间接超链接:
1
2
3
`APEC奇闻`_
.. _APEC奇闻: APEC蓝_
  • 第七种,无内容超链接:
1
.. _回首页:

图片

图片支持属性定义:

1
.. image:: 图片地址 :align: left

在文字中间插入图片:

1
2
3
这个在\ |a|\ 中插入图片
.. |a| image:: url

其中 =|a|= 这种形式叫别名.

别名

可以定义别名的元素有文本、链接、图像等:

1
2
3
4
5
6
7
8
9
10
11
12
.. |别名| replace:: 字符串 (可以是独立链接)
.. _链接: 目标地址
.. |别名| replace:: 链接_
.. |当前时间| date:: %H:%M
.. |图片名称| image:: 图片路径
:width: 宽度
:height: 高度
:target: 目标链接

表格

复杂点得表格:

1
2
3
4
5
6
7
8
9
10
11
+------------+------------+-----------+
| Header 1 | Header 2 | Header 3 |
+============+============+===========+
| body row 1 | column 2 | column 3 |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
| body row 4 | | - blocks. |
+------------+------------+-----------+

简单点得表格:

1
2
3
4
5
6
7
8
9
10
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======

注解与引用

1
2
3
4
这是一个注解[1]_,这又是一个注解[2]_
.. [1] 第一个注解
.. [2] 第二个注解

引用和注解的不同之处,就是使用具体引用文字代替数字:

1
2
3
这是一个引用[APEC蓝]_,非常蓝,格外蓝
.. [APEC蓝] 具有中国特色的蓝色天空,类似麒麟,可遇不可求

块引用

:: 开始,后面接一个空行,则属于块引用,其内容原样输出:

1
2
3
4
5
6
7
8
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.

特殊内置注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
.. contents:: 索引
:depth: 3 标题搜索深度
.. image :: (路径)/image.png
:target: http://ubuntu.org.cn
.. figures :: 形状/figures.png
.. sidebar:: 侧边栏标题
:subtitle: 子标题
These lines are sidebar content interpreted
as body elements.
.. rubric:: 醒目提示(内容)
.. topic:: 话题
.. tip:: tip内容
.. note:: note内容
.. warning:: warning内容
.. important::
.. attention::
.. danger::
.. error::
.. caution::

不显示空格

有些地方由于标记的需要,需要留空格,但最终结果又不应该显示此空格,则可以用转义字符:

1
H\ :sub:`2`\ O

读取其他rST文件

1
2
3
4
5
6
7
8
9
.. header:: 源文件路径,读取到文件头部
.. include:: 源文件路径,按顺序读取
.. footer:: 源文件路径,读取到文件尾部
.. header:: dir/header.rst
.. include:: dir/1.rst
.. include:: dir/2.rst
.. include:: dir/3.rst
.. footer:: footer.rst

嵌入代码

如:

1
2
.. code-block:: python
print "Hello"

又如:

1
2
3
.. code-block:: console
echo "Hello"

还有:

1
2
.. code-block:: bash
$ pip install redis-py

后记

Sphinx生成的文档十分精美,虽然生成中文PDF有点差强人意,但生成中文epub文件可是一点问题都没有;看来要从Org-Mode转向reStructuredText了。

资料

吴羽舒 wechat
欢迎您扫一扫上面的微信公众号,订阅我的博客!