Sphinx与reStructuredText
目录
1 前言2 Sphinx简单使用2.1 安装工具2.2 新建文档项目2.3 生成特定格式文档3 GitHub Webhook4 本地使用RTD主题5 Sphinx生成pdf的中文支持问题6 reStructuredText标记6.1 注释6.2 标题6.3 段落6.4 字体格式6.5 文字解释标记6.6 超链接6.7 图片6.8 别名6.9 表格6.10 注解与引用6.11 块引用6.12 特殊内置注释6.13 不显示空格6.14 读取其他rST文件6.15 嵌入代码7 后记8 资料
1 前言
如果是Python程序员，应该对 reStructuredText 不会陌生，结合 Sphinx 工具来写文档就更加便捷；同时，写好的文档可以托管到RTD .
工作流可以是这样: 在GitHub建立一个项目用于写文档，文档使用 Sphinx结合reStructuredText 或 mkdocs结合Markdown 格式，设置WebHook连接到ReadTheDocs自动更新。
2 Sphinx简单使用
2.1 安装工具
$ sudo pip install sphinx sphinx-autobuild
2.2 新建文档项目
$ mkdir docs$ cd docs$ sphinx-quickstart
2.3 生成特定格式文档
$ make html$ make latexpdf$ make epub
3 GitHub Webhook
Go to the
Settings page for your projectClick Webhooks & ServiceIn the Services section, click Add serviceIn the list of available services, click ReadTheDocsCheck ActiveClick Add service
这样设置后，一旦GitHub上的项目更新了，则会自动更新ReadTheDocs上的文档。
4 本地使用RTD主题
$ sudo pip install sphinx_rtd_theme
更新config.py:
import sphinx_rtd_themehtml_theme = "sphinx_rtd_theme"html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
5 Sphinx生成pdf的中文支持问题
目前看来几个文档，如果不想认真地去学一遍Tex的话，还真没有很好地解决方法，暂时可以修改config.py:
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:
$ make latex$ cd _build/latex/$ xelatex *.tex
6 reStructuredText标记
6.1 注释
以 .. 开头的是内部注释，不会显示在结果文件中，必须以其开头，前面不可有空格.
6.2 标题
如:
標題========================小標題------------------------
6.3 段落
中间空一行即可.
6.4 字体格式
**粗體***斜體*``保持原样输出``
6.5 文字解释标记
通过 `` 来实现更多功能的标记.
连结:
`something`_.. _something: www.example.com
锚标记:
_`something`
创建锚标记后，其他地方如果引用这个锚标记，则可以在文档内交叉引用。
通过 :sub: 和 :sup: 来支持下标与上标:
:sub:`下标内容``上标内容`:sup:
6.6 超链接
第一种，直接写一个网址第二种，为文字指定一个超链接(需要的时候可以使用转义字符，用于转义空格):
`APEC蓝`_.. _APEC蓝: www.example.com
第三种，内嵌超链接
`APEC蓝<www.example.com>`_
第四种，无名超链接:
Python is `one of the best scripting language`__ in the world... __: www.example.com
第五种，文件内部标题自动作为连结地址，可以建立文件内部连结:
`第一章`_
第六种，间接超链接:
`APEC奇闻`_.. _APEC奇闻: APEC蓝_
第七种，无内容超链接:
.. _回首页:
6.7 图片
图片支持属性定义:
.. image:: 图片地址 :align: left
在文字中间插入图片:
这个在\ |a|\ 中插入图片.. |a| image:: url
其中 |a| 这种形式叫别名.
6.8 别名
可以定义别名的元素有文本、链接、图像等:
.. |别名| replace:: 字符串 （可以是独立链接）.. _链接: 目标地址.. |别名| replace:: 链接_.. |当前时间| date:: %H:%M.. |图片名称| image:: 图片路径 :width: 宽度 :height: 高度 :target: 目标链接
6.9 表格
复杂点得表格:
+------------+------------+-----------+| 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. |+------------+------------+-----------+
简单点得表格:
===== ===== ====== Inputs Output------------ ------ A B A or B===== ===== ======False False FalseTrue False TrueFalse True TrueTrue True True===== ===== ======
6.10 注解与引用
这是一个注解[1]_，这又是一个注解[2]_.. [1] 第一个注解.. [2] 第二个注解
引用和注解的不同之处，就是使用具体引用文字代替数字:
这是一个引用[APEC蓝]_，非常蓝，格外蓝.. [APEC蓝] 具有中国特色的蓝色天空，类似麒麟，可遇不可求
6.11 块引用
以 :: 开始，后面接一个空行，则属于块引用，其内容原样输出:
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.
6.12 特殊内置注释
.. 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::
6.13 不显示空格
有些地方由于标记的需要，需要留空格，但最终结果又不应该显示此空格，则可以用转义字符:
H\ :sub:`2`\ O
6.14 读取其他rST文件
.. header:: 源文件路径，读取到文件头部.. include:: 源文件路径，按顺序读取.. footer:: 源文件路径，读取到文件尾部.. header:: dir/header.rst.. include:: dir/1.rst.. include:: dir/2.rst.. include:: dir/3.rst.. footer:: footer.rst
6.15 嵌入代码
如:
.. code-block:: python print "Hello"
又如:
.. code-block:: console echo "Hello"
还有:
.. code-block:: bash $ pip install redis-py
7 后记
Sphinx生成的文档十分精美，虽然生成中文PDF有点差强人意，但生成中文epub文件可是一点问题都没有；看来要从Org-Mode转向reStructuredText了。
8 资料
http://read-the-docs.readthedocs.org/en/latest/getting_started.htmlhttp://docutils.sourceforge.net/rst.htmlhttp://seisman.info/chinese-support-for-sphinx.htmlhttp://jerrypeng.me/2011/12/sphinx-chinese-pdf/http://my.oschina.net/yangbajing/blog/170262http://sphinx-doc-zh.readthedocs.org/en/latest/http://www.openfoundry.org/tw/foss-programs/9018-sphinx-restructuredtexthttp://docutils.sourceforge.net/docs/user/rst/quickstart.htmlhttp://docutils.sourceforge.net/docs/user/rst/quickref.htmlhttp://docutils.sourceforge.net/docs/ref/rst/directives.htmlhttp://wstudio.web.fc2.com/others/restructuredtext.htmlhttp://sphinx-doc-zh.readthedocs.org/en/latest/contents.htmlhttp://sphinx-doc-zh.readthedocs.org/en/latest/rest.html
▲
作者简介：
朱春来(Leslie Zhu)，金融工程师，毕业于西安电子科技大学, 喜欢历史，喜欢编程. 日常在GNU/Linux环境下进行C/C++、Python开发，对Common Lisp、Node.js、金融等感兴趣。可以通过邮箱(pythonisland@gmail.com)联系他，或者直接在他的个人主页上留言.
访问朱春来(Leslie Zhu)的个人主页(http://lesliezhu.github.com)
原文地址：Sphinx与reStructuredText, 感谢原作者分享。 接受失败也等于给了自己从零开始的机会，接受失败更是一种智者的宣言和呐喊;