Snippets-VSCode与restructuredText

Posted on Edited on Views:
Symbols count in article: 4.5k Reading time ≈ 4 mins.
使用Snippets在VSCode上更好地书写reStructuredText文档。

Snippets & reStructuredText

标题太长了，特别是reStructuredText一词，在下文中统称为RST。

前言

为什么放着好好的Markdown不用，跑去用reStructuredText呢？这个还要从我的一个翻译项目说起。

想在导师的项目里打打杂，于是就研究起了R包的开发。但是国内网络上关于R包开发的资料实在是太少太旧了，因此想要学习翻译一下英文资料 R Packages 第二版。使用Google翻译翻译到一半（我好菜啊~），发现Markdown格式的文档不好像书一样阅读，于是打起了ReadTheDocs和Sphinx的主意。

R_Packages_zh_CN Repo: https://github.com/YuanchenZhu2020/R_Packages_zh_CN

Web Book: https://r-packages-zh-cn.readthedocs.io/zh_CN/latest/

不得不说，现在Markdown使用广泛，但是它的语法没有统一标准，方便但可移植性不强；而RST貌似只在Python社区才有较广泛的使用（Python官方文档就是用Sphinx和RST书写的），但是它功能更多，可移植性好。

Snippets

“片段”

在 VSCode 里的作用就和它的中文意思一样，输入关键词，进行代码片段的自动补全。

官方说名参考这里

中文参考这里

准备

VSCode + reStructuredText插件

创建用户Snippet文件

Ctrl + Shift + P打开命令面板，输入Snippets，目标为：

点击后输入目标代码语言：

打开文件，按照里面的注释输入Json格式的代码即可：

1
2
3
4
5
6
7
8
9
// Example:
// "Print to console": {
// 	"prefix": "log",
// 	"body": [
// 		"console.log('$1');",
// 		"$2"
// 	],
// 	"description": "Log output to console"
// }
  • "Print to console"：代码段的名字；
  • "prefix": "log",：关键词；
  • "body":：需要添加的代码片段，具体如何写参照Snippets；
  • "description":：对于这段代码片段的说明；

疑问

在reStructuredText插件中已经有了Snippets，为什么我们还要再写一个呢？

这是因为，在中英文混排的情况下，里面补全的命令需要首尾各添加一个\<Space>隔开命令才能解析。而首尾各添加一个<Space>也能让命令正常解析，但是会多出首尾空格。例如：

1
2
3
4
5
6
7
8
9
10
11
.. 不能正常输出加粗效果
你的**Name**是？
.. 输出：你的**Name**是？

.. 能正常输出加粗效果
你的 **Name** 是？
.. 输出：你的 Name 是？

.. 能正常输出加粗效果
你的\ **Name**\ 是？
.. 输出：你的Name是？

因此自带的代码补全在中英文混排的情况下会很麻烦，我们需要新的代码片段。

我的模板

暂时只添加了：

  • 文字链接
  • 斜体
  • 加粗
  • 下标
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Using in mixed writing in Chinese and English
"Create Link": {
    "prefix": "link",
    "body": "\\ `$1 <${CLIPBOARD}>`__\\ ",
    "description": "Create link using link in the clipboard."
},
"Create Emphasize": {
    "prefix": "emp",
    "body": "\\ *$1*\\ ",
    "description": "Create format of emphasized text"
},
"Create Strong": {
    "prefix": "str",
    "body": "\\ **$1**\\ ",
    "description": "Create format of strong text"
},
"Create Subscript": {
    "prefix": "sub",
    "body": "\\ :sub:`${subscript}`\\ "
}

还能怎么用？

比如添加一个C语言文件头注释？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
	// Create header comments in c codes
	"Header Comments": {
		"prefix": "com",
		"body": [
			"/*",
			"** @FileName: ${TM_FILENAME_BASE}.c",
			"** @Author: ${1|name_1,name_2|}",
			"** @Date: ${CURRENT_MONTH}-${CURRENT_DATE}-${CURRENT_YEAR}",
			"** @Version: ${2:0.0.1}",
			"** @Description: ${3}",
			"** @Encoding: ${4|UTF-8,GBK,GB2312|}",
			"*/",
			"$5"
		],
		"description": "Create filename, author, date, version, description in header."
	}
}

比如 Latex 文章模板？

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
	// Article written in Chinese and English
	"Write article": {
		"prefix": "write",
		"body": [
			"% -*- encoding: utf-8 -*-",
			"% ${TM_FILENAME_BASE}.tex",
			"",
			"\\documentclass[UTF8]{ctexart}",
			"\\usepackage{amsmath}",
			"\\usepackage{graphicx}",
			"\\usepackage{listings}",
			"\\usepackage{geometry}",
			"\\geometry{left = 1.5cm, right = 1.0cm, top = 2.5cm, bottom = 2.5cm}",
			"\\title{$1}",
			"\\author{${2:名字}}",
			"\\date{\\today}",
			"\\begin{document}",
			"\\maketitle",
			"\\tableofcontents",
			"\\section{$3}",
			"",
			"%\\begin{equation}",
			"    %",
			"%\\end{equation}",
			"",
			"\\section{$4}",
			"",
			"\\begin{enumerate}",
			"    \\item",
			"\\end{enumerate}",
			"",
			"\\section{$5}",
			"",
			"\\begin{lstlisting}[language=]",
			"",
			"\\end{lstlisting}",
			"",
			"\\section{$6}",
			"",
			"%\\begin{figure}[h]",
    		"%\\centering",
    		"%\\includegraphics[width=0.9\\textwidth]{}",
			"%\\end{figure}",
			"",
			"\\end{document}"
		],
		"description": "Model of Latex Article Written in Chinese and English."
	}
}