python自动生成易于阅读的html文档——使用Sphinx

Sphinx是一组可以用来从文本树生成一个HTML结构的脚本和docutils扩展。这个工具可以用来创建python文档,现在很多项目都使用它来制作文档。使用它内建的功能,生成一个真正精细的浏览系统,以及一个简单但足够用的客户端javascript搜索引擎。

使用方法:

1.easy_install Sphinx

2.sphinx-quickstart   #生成目录结构,一路yes,回车

生成的source目录下会有一个index.rst文件,使用reStructured格式编辑它就可以了

3.运行make html #将会生成html文件,在build目录下

4.运行build/html目录下的index.html文件即可

reStructuredText 简明教程
060724 17:58

 

作者:
Laurence
邮箱:
2999am@gmail.com
ID:
Kardinal @ Ubuntu.org.cn 论坛
版权:
This document has been placed in the public domain
参考:
《结构化文本入门(Karron Qiu)》 《Quick reStructuredText》 《Vim reStructuredText》 《reStructuredText Interpreted Text Roles》

  • WYTIWYG & WYSIWYG
    • 所见即所得
    • 所想即所得
  • reStructuredText
  • 基本元素
    • 字串元素
    • 行元素
    • 块元素
  • 特殊元素
    • 页面元素
    • 行块元素
    • 超级块元素
    • 物件元素
    • 自定义元素
  • 对象
    • 标题
    • 行内
    • 脱字符
    • 链接
    • 物件别名
    • 列表
    • 表格
    • 脚注
    • 提示符引用
    • 预定义
  • 项目管理
  • 搭建reStructuredText环境
    • Linux
    • Windows
  • reStructuredText命令
  • 定制
  • 代码风格
    • 缩进
    • 空行
    • 下划线
    • 标题
    • 标题链接
    • 表格
    • 别名
    • 链接
    • 列表
  • 编辑器设定
    • Vim
    • Emacs
  • FAQ
    • 空行
    • 消除空格
    • 缩进和空格
WYTIWYG & WYSIWYG
所见即所得
WYSIWYG ( What You See Is What You Get )
这个概念非常流行。就是说制作过程中所见到的,和最终所得到的结果一致。
比如我用DW编辑一个网页文件,在编辑的过程中,我可以设定内容的格式、排版、色彩等属性,而最终得到的网页,完全符合了我的愿望。
我们都知道,网页文件使用的是 Html 标记语言。比如加粗某处文字,我们要使用标签 <b> ,然后是我们要加粗的文字,比如 粗体 最后再使用标签 </b> 来结束它,不然的话, 粗体 后面的文字也要被加粗了…… 因为 Html 解析器 (一般来说,就是浏览器)没法子判断到底在哪儿结束“加粗”这一行为。源文件大致是这样的:
<b> 粗体</b>
一个完整的Html文件就是由许许多多这样的标签构成的。标签和标签之间可以嵌套。比如:
<html>
<head> 头部</head>
<body>
<p>    正文                                               </p>
<p>    这里是段落2                                          </p>
<p>    这里是<b>粗体</b>,这里是<font color=red>红色字体</font></p>
</body>
</html>
当然了,大多数时候,Html的源文件比较复杂,远远没有这么简单。可不要被它可怕的外表吓坏了,一个Html文件,无论多么复杂,它总是具有这种结构,只要您熟悉了足够多的标签,Html对于您来说,完全是纸老虎:)
必须承认的是,如果没有所见即所得的工具,比如 DW ,直接使用Html语言编写网页文件,那应该不会是一种享受-_-#
可能有许多高手会讲: 我就是喜欢直接编辑Html代码,那绝对是一种享受!
是啊,可能那是一种享受,但是你享受的是编写代码,而不是设计页面。 Html并不是编程,代码不是决定因素,而外观设计才是重要的。所见即所得把开发者从代码中解救出来,使它们把心思都用在设计上,这才是它的伟大之处!
同样的,Word之类的工具,也是一种所见即所得的工具。不同的是,doc 文件的复杂程度要远远高于 Html,您不太可能直接编辑它。
所想即所得
WYTIWYG ( What You Think Is What You Get )
我们已经知道了,所见即所得偏重的是外观设计,而不是代码。看起来不错,不过这种模式也有一些缺点。
比如我想强调某事,我可能就会有点犹豫……我是应该用粗体呢?还是应该用红色的字体?还有什么其它更好的方法么?
假如现在我使用的是白色的背景,我使用红色的字体来表示强调。由于各种可能的原因,我需要把这些内容转移到另外一个地方,不巧的是,那个页面的背景使用的颜色和红色比较接近,比如说粉红色吧,如此一来,我的红色的文字反而没有正文的黑色文字醒目,本来是表示强调的,反而成了忽视……
如果手动修改这些地方,可能会非常的麻烦,因为我可能用红色表示强调,用粗体表示感叹…… 而这些内容可能会出现在许多不同的场合,这可怎么办啊?
这个问题很容易解决,答案就是 所想即所得 !例如:
这里是<强调>强调</强调>,这里是<感叹>感叹</感叹>
……
再使用一个样式定义,例如:
强调 = 红色字体
感叹 = 粗体
……
然后使用转换程序,根据预先定义的样式,自动将 <强调> 转换为 <b> ,将 <感叹> 转换为 <font color=red> 就可以了。
如果我们想将强调改用绿色,只要将样式定义改一下:
强调 = 绿色字体
也可以方便的转换为其它文件,比如 pdf 或者其它格式──只要有相应的转换程序就可以了。
所见即所得工具不需要编写代码,将开发者从代码只解救出来,使其专注于设计;而所想即所得工具不需要设计外观,把设计者从外观中解救出来,使其专注行思考!
事实上,这种使用标签的模式比较接近 DocBook ,当然了,标签不会是中文的。从国际主义精神的角度,我们要照顾到外国友人──据说外国友人的中文普遍不太好:)
从通用性的角度来考虑,标签基本上使用英文;从减少输入的角度考虑,标签应该尽量简短 ──很多标签使用缩写。
不过标签这种方式本身就很麻烦,特别是使用尖括号的标签。能不能再简单一些呢?
reStructuredText
re Structured Text ,重构建文本,是一种优秀的写作工具,对于元素的定义已经不只是简化,而是进行了充分的优化。
上面我们提到了元素,我们把它理解为一个对象的基本组成部分。例如 <b>粗体</b> 、 <强调>强调</强调> 都是元素,只是组成的方式不同而已,一种是所见即所得,另一种是所想即所得。
<bold> 到 <b> 是一种简化,不过还是很麻烦。使用一些不常用而且又容易输入的符号,例如 ** 就是优化了
reStructuredText 中,正是使用 ** 来表示强调!

 

原始内容
显示结果
* 强调*
强调
** 特别强调**
特别强调
``* 原文引用*``
* 原文引用*
/* 原文*
* 原文*

基本元素
这一部分内容十分重要,理解透彻后便能够无往而不利。
不然的话,在实际使用的过程中,您可能会觉得 reStructuredText 比较莫名其妙,有点怪怪的……
字串元素
连续的字符串构成的元素,为字串元素。 看下面的例子
** 强调** 就是一个字串元素。普通文本也是一个字串元素。
    第三个字串元素
** 强调** 是第一个字串元素;它后面的文本,是第二个字串元素。
如果您够细心,您会发现,字串元素之间使用 空格 分隔。在字串元素的级别, 缩进换行符 也能够分隔字串元素。
严格来说,字串元素 空格 . , ? ! 等英文标点结束
行元素
下划线(有时包括上划线)和文本构成的元素,例如标题、表格
标题
====
表格:
===== ===== ======
   Inputs     Output
------------ ------
A      B    A or B
===== ===== ======
False False False
True   False True
False True   True
True   True   True
===== ===== ======
行元素中,下划线使用符号构成,例如
Chapter 1 Title
===============
Section 1.1 Title
-----------------
Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~
构成下划线的符号长度,应不小于文本长度。(一个汉字占两个字符)
块元素
具有相同缩进的元素为块元素,例如段落、表格
┊   第一行
┊   第二行
┊   第三行
┊   第二段
块元素使用一个 空行 结束,也就是一个 垂直分隔符 。上面的例子中包含了两个块元素。
连续出现多个空行时,作为一个空行处理。
可以使用 Line Blocks 增加空行,使单独一行中只有一个 | 符号即可
(前后都要有空行,因为它也是一个 块元素)
见 行块元素
技巧: 只要没有空行,不管换多少次行,都会处理为一行。建议您将每行的内容控制在50个汉字或者100个字母之内,尽量在标点符号处手动换行,以增加源文件的可读性。
块元素也允许逐行增加缩进,例如
┊   第一行
┊   第二行
┊     第三行
┊                        第四行
相同缩进的行处理为一行;不同缩进,无论缩进多少,都处理为一个缩进。上面文本实际显示为
┆    第一行第二行
┆        第三行
┆            第四行
段落的缩进由其首行缩进决定
事实上,这种形式属于 定义列表
注意: 字串元素 可以作为 行元素 的子集,它们都可以作为 块元素 的子集。
特殊元素
这部分内容稍微复杂,建议您动起手来,摸着石头过河。
搭建reStructuredText环境 和 reStructuredText命令部分内容,您可以先参考一下:)
当然了,前面部分的内容,尽管看起来比较简单,不过您还是可以实验一下,多少会有一些帮助的……
页面元素
类似行元素,但是不包含缩进,例如标题、分隔线
==============
文档标题
==============
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ( 分隔线)
章节标题
===========
二级章节标题
-----------
二级章节标题
-----------
章节标题
===========
行块元素
在某些情况下,一个段落中需要用逐行向外缩进,比如中文排版;
段落首行
第二行向外缩进
其它行和第二行相同
或者手动换行而不分段,甚至是更加复杂的装饰性文字……
<>
< >
< <> >
< >
<>
而段落中只能逐行向内缩进;相同的缩进会自动合并为一行,不能手动换行
这些问题可以使用 行块元素 来解决。
在每一行起始处添加引导符 | 缩进
|          段落首行
|       第二行向外缩进
|       其它行和第二行相同
相邻的行块元素,它们的引导符缩进应相同。
行块引导符后的一个空格为分隔符,是必须的!处理时忽略
超级块元素
类似块元素,但是可以包含空行,并且内部可以随意缩进。例如注释、块引用
包含有超级块引导符的行为引导行。超级块起始时相对引导行向内缩进;结束时使用一个空行,并且向外缩进等于或者超过引导行
外部块
引导行 <引导符>
      向内缩进
    超级块内部可以自由缩进
    可以使用空行
新的开始.这一行前需要空行,起码与引导行缩进相同,或者更外
注释
注释是以 .. 起始的超级块元素,注释中的内容只在源文件中显示,并不在结果中显示
.. 注释
第二行
第三行
第二段
第六行
新的开始
引导符 .. 前不能有其它字符,之后要有一个空格与注释内容分隔开( .. 同时是一个字串元素,前后都要有分隔符)
块引用
块引用是以 :: 起始的超级块元素,块引用的内容不作任何处理,以原文显示
块引用 ::
第一行
第二行
第四行
新的开始
引导符 :: 后必须有一个空行
物件元素
用来定义一个物件,物件元素由行内字串元素或注释中的块元素构成
_ 结尾的字串元素,例如 链接_ [脚注]
| 包裹的字串元素,例如 |别名|
它们都需要在注释中进行解释:
这里是一个 链接_ 。 [脚注]_
.. _ 链接: http://xxx
.. [ 脚注] xxxxxx
.. note:: 注意
一些具有特殊功能的物件,比如索引 contents:: ,被直接写到注释中去
.. image:: 图片
.. contents:: 索引
参见 预定义
自定义元素
例如文档信息,实际效果见页面顶部
: 作者: Laurence
: 邮箱: 2999am@gmail.com
:ID: Kardinal
: 版权: This document has been placed in the public domain
: 参考: 《Quick |rst| 》《结构化文本入门(Karron Qiu)》
.. 技巧:: 自定义
使用以下格式
:< 名称>:`字符串`
.. < 名称>:: 字符串
在Html输出中添加
<span class="< 名称>">字符串</span>
re Structured Text 系统内建了许多预定义对象,来完成特定功能。见 预定义
对象
标题
re Structured Text 会根据下划线读取文档的标题,并且可以自动组织索引
=====================
文档标题
=====================
--------
子标题
--------
章节标题
========
...
具有同样带修饰线类型的标题,属于树状索引的同一层级
带有上划线的标题,和不带上划线的标题是不同类型。上面例子中,文档标题和章节标题就不属于同一层级
自上而下,越先出现的标题类型,层级越高
为了简单起见,我们只写标题的修饰线
===
---
---
^^^
^^^
^^^
---
---
^^^
我们可以看到,自上而下,最先出现的标题是 === ,所以它处于最高层级;然后是 --- ,所以它处于第二层;最后是 ^^^
如果画成树形图,就是这样的
===
├ ---
├ ---
│   ├ ^^^
│   ├ ^^^
│   └ ^^^
├ ---
├ ---
│   └ ^^^
行内
多表示语气,如 **强调**

 

源文本
显示结果
说明
* 强调*
强调
通常显示为斜体
** 特别强调**
特别强调
通常显示为粗体
` 字符串`
字符串
字符串内包含空格和标点符号时,处理为单个字串
`` 行内引用``
行内引用
显示为等宽字体,保留空格,不断行
简单链接_
简单链接
简单的链接名称 <链接名称>_
` 词组 链接`_
词组链接
带空格、标点的链接名称
无名链接__
....Ubuntu.......
链接目标中不使用名称。适合大段文字的链接
_` 链接目标`
链接目标
链接的实际指向 _<链接名称>:
| 物件别名|
用来给物件指定一个别名。文本、图片、链接及其它
脚注名称 [1]_
[1]
见脚注
引文名称 [引文]_
[ 引文]
见引文
http://...
http://...
独立链接

.. _ 简单链接:
.. _` 词组 链接`:
__ http://forum.ubuntu.org.cn/    无名链接
.. | 物件别名| image:: http://forum.ubuntu.org.cn
   /templates/subSilver/images
   /folder_big.gif

 

[1]
脚注1

.. [1] 脚注1

 

[ 引文]
内容

.. [ 引文] 内容
脱字符
re Structured Text 使用 / 作为脱字符,脱字符引导的字串元素不具有特殊涵义,以本来面目显示

 

** 强调**
强调
/** 强调**
** 强调**

输入 / 字符,可以使用 //
Tip
使用 脱字符+空格 (/_)作为分隔符,可以消除字串元素之间的空格
链接
链接主要包括以下几种
独立链接 reStructuredText 会自动将网址转换为链接。
例如 http://www.ubuntu.org.cn/
http://www.ubuntu.org.cn/
命名链接 ,为链接命名,有助记忆和减少空间占用。
在正文中使用 <链接名>_ ,注释中使用 _<链接名>: [链接目标]
例如 Ubuntu
Ubuntu_
.. _Ubuntu: http://www.ubuntu.org.cn/
如果链接名中出现空格和标点符号,可以使用 ` 将链接名包裹起来
`Ubuntu cn`_
.. _`Ubuntu cn`: http://www.ubuntu.org.cn/
无名链接 ,不使用链接名的链接
主要用于将大段文字转换为链接。如果将这部分文字作为链接名,链接名也将被写进注释中……
` 主要用于将大段文字转换为链接。如果将这部分文字作为链接名,
链接名也将被写进注释中……`__
__ http://www.ubuntu.org.cn/
无名链接经常与命名链接一起使用
` 这里是一大段文字………………`__
__ 一个命名链接_
可以在任意位置定义这个命名链接
.. _ 一个命名链接:
锚点 ,链接的目标地址留空,可以在当前位置标记锚点。
跳转到 锚点_
.. _ 锚点:
< 页面位置>
点击锚点名称跳转到锚点标记处。
标题链接 ,跳转到文章内部的标题
re Structured Text 定义标题的同时,还定义了一个标题链接,在正文中使用 标题名称_ 可以跳转相应标题
标题名称
========
跳转到 标题名称_
嵌入式链接 ,链接目标嵌入到链接中。(reStructuredText 中没有通过,不建议使用)
`Ubuntu <http://www.ubuntu.org.cn>`_
物件别名
为一个物件元素定义一个别名
|H2O|
.. |H2O| replace:: H/ :sub:`2`/ O
输入 |别名| 便可以得到所定义的内容
上面例子中,输入 |H2O| ,得到 H/ :sub:`2`/ O ,也就是 H2O
可以定义别名的元素有 文本 链接 图像 Unicode字符 日期时间等
链接:
.. | 别名| replace:: 字符串 (可以是独立链接)
.. _ 链接: 目标地址
.. | 别名| replace:: 链接_
为链接创建别名时,使用命名链接,则别名替换为链接名称;使用独立链接,则别名替换为目标地址。
为链接创建别名的时候,可以随意修改目标地址,但是链接名称要使两处保持一致,不够方便;并且使用别名时一定要带链接,不够灵活
我们建议您使用 别名链接 ,它能够方便的修改链接名称和目标地址,并且可以灵活的输出各种格式
别名链接 ,使用一个别名,定义链接名称和目标地址。
这是一个 |别名链接|_
.. | 别名链接| replace:: 实际显示的链接名称
.. _ 别名链接: http://目标地址
实际相当于先定义一个别名,然后定义别名的链接。
Note
·         | 别名链接| 输出replace定义的字符串
·         别名链接_ 输出使用别名作为链接名称的链接
·         | 别名链接|_ 输出链接名称定义的链接
图片:
.. | 图片名称| image:: 图片路径
   :width: 宽度
   :height: 高度
   :target: 目标链接
Unicode 字符:
.. | 别名| unicode:: U+211
.. |200E| unicode:: 200 U+20AC
时间日期:
.. | 当前时间| date:: %H:%M
列表
列表中,相同的层级使用相同的缩进。列表中的所有条目都是块元素,要使用空行分隔
列表中同一层级不需要空行分隔。不同层级起始处必须有空行
列表:
- 条目
- 条目
      - 条目
      - 条目
- 条目
·   如果不包含复杂的层级,只要使用缩进开始列表,并且不需要空行
·   如果层级复杂,那么最好所有条目都以空行分隔,避免发生混乱
要点列表 - + ** 和一个空格作引导符,条目不计数
·   第一条
o      子条目一
§ 第三级
§ 第三级
o      子条目二
·   第二条还是第一行
第二条第二行
o      子条目
·   第三条
代码如下 :
- 第一条
- 子条目一
     - 第三级
     - 第三级
- 子条目二
- 第二条
还是第一行
第二条第二行
- 子条目
- 第三条
枚举列表 使用一个数字或者字符,后跟 . ) 或者使用 () 括起来,加一个空格
1. 数字
A. 大写字符
a. 小写字符
    3. 用不同数字开始的子列表
    4. 确认数字有正确的序号!
I. 大写的罗马字符
i. 小写的罗马字符
(1) 再来一个数字
1) 再来
可以使用 # 代替数字, reStructuredText 会自动排序
#)
#)
#)
1.   
2.   
3.   
定义列表 为列表中的条目定义一个名称
要点列表
只列出要点,条目不记数
定义列表
为列表中的条目定义一个名称
枚举列表
条目进行计数
要点列表
只列出要点,条目不记数
定义列表
为列表中的条目定义一个名称
枚举列表
条目进行计数
区块列表 ,常用作联系薄
: 作者: Laurence
: 邮箱: 2999am@gmail.com
:ID: Kardinal @ Ubuntu.org.cn 论坛
: 版权: This document has been placed in the public domain
: 参考: 《结构化文本入门(Karron Qiu)》
      《Quick |rst|/ 》
      《Vim |rst|/ 》
      《/ |rst| Interpreted Text Roles》

 

作者:
Laurence
邮箱:
2999am@gmail.com
ID:
Kardinal @ Ubuntu.org.cn 论坛
版权:
This document has been placed in the public domain
参考:
《结构化文本入门(Karron Qiu)》《Quick reStructuredText》《Vim reStructuredText》《reStructuredText Interpreted Text Roles》

表格
表格使用一条带有分隔符的上划线,和最少一条下划线构成
========   ==========
表格        表格
========   ==========
上划线下面为多行缩进相同的 行元素,行元素的下划线应不短于行字符。
表格同一列的下划线,长度应相等。
上划线(顶部)的分隔符是必须的,它决定了表格可以拥有的列数,但是不影响相邻列的合并。
合并相邻的列,只要取消下划线的分隔符就可以了。
底部的下划线,应和上划线使用同样符号
===== ===== ===== ===== =====   以空格作分隔符,间距均匀。决定了这个表格最多可以有5列
11    12    13    14    15
----------- -----------------   下划线的长度应不小于字符长度
21    22    23    24    25
----- ----- ----- ----- -----   每一行的下划线,决定了相信列是否合并
31    32    33    34    35
----- ----------- -----------   如果不打算合并列,可以取消表内分隔线
41    42    42    44    45
=============================   底线必须与上划线使用相同符号

 

11 12
13 14 15
21
22
23
24
25
31
32 33
34 35
41 42 42 44 45

如果想制作更复杂的表格,例如合并相邻行,则需要使用列分隔线
+------------+------------+-----------+
| 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]_
.. [1] 这里是脚注的内容
行内脚注后面也有一个 _ 符号,它是当作一个链接处理的。
脚注的名称可以使用 数字 # * ,使用数字时需要手机排列
推荐使用 # 作为脚注名称, reStructuredText 会自动计数。使用 * 作为脚注名称, reStructuredText 会把它们替换成一些花哨的符号
提示符引用
使用 >>> 作为引导符,模仿交互式命令提示行
>>> rst2html -r 4 --stylesheet-path=/home/user/html4css1.css rst html
引用块不能空行
原文本
>>> rst2html -r 4 --stylesheet-path=/home/user/html4css1.css rst html
预定义
re Structured Text 中内建了许多字串元素作为功能对象
标准。行内使用:
:emphasis:
* 强调*
:emphasis:` 强调`
:literal:
`` 原文``
:literal:` 原文`
:strong:
** 特别强调**
:strong:` 特别强调`
:subscript:` 下标`
:sub:` 下标`
:superscript:` 上标`
:sup:` 上标`
:title-reference:` 标题`
:title:` 标题`
:t:` 标题`
特殊。注释中使用:
.. 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::
字串元素间使用脱字符和空格作为分隔符,可以不显示空格,例如:
H2O
H/ :sub:`2`/ O
项目管理
编写一个较大规模的文档时,使用单一源文件,编辑起来可能十分吃力。
re Structured Text 允许使用一个文件,在转换时将其它文件的内容读取进来,以便更好的管理文档项目
.. header:: 源文件路径,读取到文件头部
.. include:: 源文件路径,按顺序读取
.. footer:: 源文件路径,读取到文件尾部
例如:
.. header:: dir/header.rst
.. include:: dir/1.rst
.. include:: dir/2.rst
.. include:: dir/3.rst
.. footer:: footer.rst
Note
不能够递归读取
搭建reStructuredText环境
Linux
Ubuntu 或者 Debian 系统中,使用APT安装
>>> sudo apt-get install python-docutils
/usr/share/python-docutils/ 目录中包含了相关的工具,我们经常要用到的工具是 rst2html.py 。
在安装好之后,系统通常自动为它建立了链接,直接运行 rst2html 命令即可。
Windows
reStructuredText命令
rst2html [参数] <源文件.rst> [目标文件.html]
如果不指定目标文件,而输出Html代码,并不生成文件
-r <levle> 设定报告级别,默认为 2
--tab-width=<width> 设定输出的缩进宽度,默认8个空格
--stylesheet-path=<file> 指定CSS文件
--embed-stylesheet 使用嵌入式CSS
--footnote-references=<format> 脚注格式。 barckets方括号 superscript上标
--compact-lists 忽略列表中多余的空行,默认 enabled
--config=<file> 指定配置文件
--footnote-backlinks 允许从脚注跳回原文,默认选项
--toc-top-backlinks 允许从标题跳回索引,默认选项
定制
/usr/share/python-docutils/docutils.conf 为配置文件
# These entries affect all processing:
[general]
source-link: yes
datestamp: %Y-%m-%d %H:%M UTC
generator: on
# These entries affect HTML output:
[html4css1 writer]
# Required for docutils-update, the website build system:
stylesheet-path: ../docutils/writers/html4css1/html4css1.css
embed-stylesheet: no
field-name-limit: 20
代码风格
缩进
尽量使用固定长度的空格作为缩进,推荐您使用 4 个空格作为一个缩进
虽然在理论上,缩进可以使用任意长度,但是那样容易引起混乱,例如:
空行
有些情况下,空行并不是必须的,比如标题和之后的内容。
不过我们建议您还是尽量使用空行,以免不必要的麻烦。
下划线
理论上,下划线只要和文字的长度相同就可以了,不过我们建议主您使用比较长,且长度固定的下划线 例如 50
标题
下划线使用的符号比较重要。
如果能够养成一个固定的习惯,在处理较大规模的文档时,可以避免许多麻烦
推荐以下几套

 

#####
=====
^^^^^
+++++
-----
>>>>>
*****
~~~~~
<<<<<

建议您使用带上划线的第一级符号作为文章标题
全部可选符号包括
= - ` : ' " ~ ^ _ * + # < >
标题链接
请尽量避免重复的标题,特别是存在大量标题链接的情况下。
如果同时存在多个名称相同的标题,并且有指向该名称的标题链接, reStructuredText 无法确定哪一个标题是真正的目标,这时就会发生错误。
而使用标题链接链接越多,发生这种错误的几率越大~
表格
表格尽量使用空格作分隔符
如果没有特殊要求,表格包含上划线和底线就可以了,例如:
======= =======
aaaaaa   111111
bbbbb    2222222
cccc     3
======= =======
别名
建议将别名定义放在页面顶部,便于维护
链接
请尽量使用独立链接、无名链接、标题链接和别名链接
定义别名链接的两行注释中间不要空行,便于阅读
.. |bmlj| replace:: ** 别名链接**
.. _bmlj:
** 别名链接**
列表
如无必要,请尽量使用要点列表和定义列表。枚举列表更适合作为章节
编辑器设定
Vim
下载 vst.vim 文件,拷贝到Vim的插件目录即可。
Emacs
安装 rst.el 插件
将如下内容添加到 ~/.emacs 文件中
;;RST
(require 'rst)
(add-hook 'text-mode-hook 'rst-text-mode-bindings)
(setq auto-mode-alist
(append '(("//.rst$" . rst-mode)
("//.rest$" . rst-mode)) auto-mode-alist))
FAQ
空行
可以使用 Line Blocks 增加空行,使单独一行中只有一个 | 符号即可(前后都要有空行,因为它也是一个 块元素)
消除空格
使用 /_ (脱字符和空格)代替空格作为分隔符,可以消除空格。
缩进和空格
它们是等效的,如果不怕麻烦,您大可以完全使用空格,而不使用缩进

 

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值