编辑 reStructuredText

2.4. 编辑 reStructuredText#

简要介绍 reStructuredText 的概念, 语法等.

reStructuredText 官网说 reStructuredText 是 Docutils (Documentation Utilities) 标记语法和解析器组件 ( Markup Syntax and Parser Component of Docutils ).

Docutils 项目的主要是为了创造一套将纯文本转换为一些常用格式的工具, 这些常用格式包括：HTML、XML和LaTeX.

reStructuredText是一个易读, 易写, 所见即所得的明文标记语法和解析系统, 对于 "in-line" 程序文档 (如 Python docstrings) 非常有用, 用于快速创建简单的网页和本地文档. reStructuredText是专为特定应用领域的扩展而设计, 其解析器是Docutils的一个组件. reStructuredText是轻量级标记系统 StructuredText 和 Setext 的修订和重解释版本.

reStructuredText的主要目的是定义和实现一个用于Python文档和其他文档域的 标记语法 , 要求是 可读的 和 简单的 , 同时 足够胜任非凡的任务 . 标记的目的是能够将reStructuredText文档转换成有用的结构化数据格式.

上面是对下面这段话的翻译:

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems.

The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.

就这些吧! 如果你现在就想尝试, 可以在线试一试: http://rst.ninjs.org/.

警告

"reStructuredText" is ONE word, not two!, 以下可能会简写成 reST.

关于为什么使用 Rest ， 我不想再多说了, 简要列举一下吧:

  • 专注于文本内容而不是排版样式

  • 兼容所有文本编辑器与字处理软件

  • 渲染导出格式丰富, 如HTML、PDF, 借助一些工具还可以导出Latex、epub等文件

  • 可以使用Git等版本控制系统管理文章版本

  • 可读、直观、易学

建立 reST 编辑环境， 正如前面所说, 你可以在线试一试: http://rst.ninjs.org/, 也可以去下载一些相关工具, 可以参考 http://stackoverflow.com/questions/2746692/restructuredtext-tool-support , 如 Docutils , Sphinx , 超级文本编辑器Sublime Text3 。

下面介绍 Sublime Text 下环境的配置.

2.4.1. Sublime Text及其安装#

Sublime Text is a sophisticated text editor for code, markup and prose. You'll love the slick user interface, extraordinary features and amazing performance.

如作者自己对ST的定位, ST是一个高雅且精良的 文本编辑器 , 由程序员Jon Skinner于2008年1月份所开发出来, 可以访问`Sublime Text主页 <http://www.sublimetext.com/>`_ 查看效果展示.

Sublime Text具有漂亮的用户界面和强大的功能, 例如代码缩略图, Python的插件, 代码段等. 还可自定义键绑定, 菜单和工具栏. Sublime Text 的主要功能包括：拼写检查, 书签, 完整的 Python API , Goto 功能, 即时项目切换, 多选择, 多窗口等等.

Sublime Text支持三大主流操作系统: Windows, Linux, OS X. 几乎你需要的功能都有, 一切可修改（快捷键、插件包etc.）, 界面优美, 可惜的是不开源, 不过即使不注册也可以使用, 功能不受限. Lime Text 是其开源版的一种实现, 我还没打算用这个.

Sublime Text的安装#

对于Windows系统, 其实是不需要安装的, 是的, 你没听错, 请访问 ST下载页面 , 并选择 便携版 (portable version), 然后解压后双击 sublime_text.exe 当然, 你也可以选择安装版, 不过我会选择便携版, 因为这样复制到其它机器上就照常用了.

对于Linux系统, 可以访问 ST下载页面 下载安装, 对于Ubuntu系统, 直接双击下载的 deb 包, 然后到软件中心单击 安装. 当然, 可以通过命令安装: sudo dpkg -i <package.deb> , 安装完成后, 终端输入: subl 即可启动ST3.

ST中插件包的安装#

在ST中可以配置各种代码编辑器环境, 一般通过安装ST的插件包来实现, Package Control 是ST的插件包管理器, 访问 Package Control 查看插件包, 插件包的安装方式一般有如下两种.

  1. 下载并解压安装包

到 Package Control 或 GitHub 搜索并下载插件包, 然后解压到ST根目录即可.

  • 对于Windows, 请解压至 Sublime Text3 x64/Data/Packages 目录下

  • 对于Linux系统, 解压至 ~/.config/sublime-text-3/Packages 下

然后, 重启ST即可.

  1. 通过Package Control安装管理包

首先需要给ST安装 Package Control 包管理器插件.

安装方法很简单, 可以参见官网：https://packagecontrol.io/installation#st3, 也可以看下面的介绍.

通过 View --> Show Console 打开打开控制台, 粘贴如下代码并回车安装

For ST3:

import urllib.request,os,hashlib; h = '2915d1851351e5ee549c20394736b442' + '8bc59f460fa1548d1514676163dafc88'; pf = 'Package Control.sublime-package'; ipp = sublime.installed_packages_path(); urllib.request.install_opener( urllib.request.build_opener( urllib.request.ProxyHandler()) ); by = urllib.request.urlopen( 'http://packagecontrol.io/' + pf.replace(' ', '%20')).read(); dh = hashlib.sha256(by).hexdigest(); print('Error validating download (got %s instead of %s), please try manual install' % (dh, h)) if dh != h else open(os.path.join( ipp, pf), 'wb' ).write(by)

For ST2:

import urllib2,os,hashlib; h = '2915d1851351e5ee549c20394736b442' + '8bc59f460fa1548d1514676163dafc88'; pf = 'Package Control.sublime-package'; ipp = sublime.installed_packages_path(); os.makedirs( ipp ) if not os.path.exists(ipp) else None; urllib2.install_opener( urllib2.build_opener( urllib2.ProxyHandler()) ); by = urllib2.urlopen( 'http://packagecontrol.io/' + pf.replace(' ', '%20')).read(); dh = hashlib.sha256(by).hexdigest(); open( os.path.join( ipp, pf), 'wb' ).write(by) if dh == h else None; print('Error validating download (got %s instead of %s), please try manual install' % (dh, h) if dh != h else 'Please restart Sublime Text to finish installation')

然后, 通过 Package Control 安装插件包.

使用 Ctrl + Shift + P 打开PackageControl, 如果没有输入 package 就出现了, 选择 Install Package , 如下图

_images/st-packagecontrol.png

接着在弹出的窗口中输入 插件包的名字 选择安装即可.

配置reST环境#

给ST安装以下插件包:

reStructuredText sublime text 的三款辅助插件#

OmniMarkupPreviewer (用于解析渲染reST等多种标记语法, 必选 ), 安装好后, 按快捷键 Ctrl + Alt + O 预览。 该插件的浏览器预览是动态预览，每当你编辑目标文件的时候，浏览器都会动态显示你编辑的内容。

reStructuredText Improved (用于语法着色, 可选 , 建议安装 )

Restructured Text (RST) Snippets (用于自动补全, 可选, 但推荐安装 ), 在制表时很有用。

补全插件 Restructured Text (RST) Snippets

该插件的 github 地址 github 地址 ，里面详细介绍了使用方式和快捷键，特别是对于表格的使用很方便，需要用到表格时最好看一下。

该插件的突出优点：表格，标题 mark 的自动补全(tab)，以及标题的升降级都有相应的快捷键，可以很好缩短编写时间。

该插件的安装虽然可以直接从 Package Control 安装，但是从 Package Control 安装的话就我观察无法修改快捷键。 因为【标题的升降级】快捷键和默认的 sublime text 快捷键有冲突(也可能是我安装了某些插件的缘故) [3] 。 但是问题是无法修改，这就很伤。 所以推荐另一种安装方式。 就是直接在 github 下载源码，解压放到 sublime text 默认插件安装的文件夹下就可以了。一般该文件夹的路径大致如下：

C:UsersAdministratorAppDataRoamingSublime Text 3PackagesUser 有可能需要重启 sublime text 才能完成安装。总之这样安装完后就能随意改变快捷键了。

Note

2.4.2. 使用vscode编写rst文件#

使用vscode编写sphinx文档非常方便，可以即时预览和自动编译。

rst vscode插件说明页：https://docs.restructuredtext.net/index.html

另外，vscode默认支持markdown单个文件的预览。

reStructuredText插件#

需要安装的vscode插件：

  • python

  • reStructuredText

安装python插件后，要选择使用python3的解释器，不要使用python2。

安装reStructuredText插件后，打开rst文件，点击预览按钮。

会提示使用sphinx还是doctuil工具，我们选择使用sphinx。

若配置正确，稍等一会即可在右侧看到预览效果。

Table Formater插件#

使用Table Formater可以方便格式化表格，支持markdown和rst https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter

插件名：Table Formatter

安装后通过Ctrl-Shift-P调用 Table: Format Current 或 Table: Format All

目录