【问题标题】：Embedding reStructuredText in Python docstrings在 Python 文档字符串中嵌入 reStructuredText
【发布时间】：2015-11-05 17:24:44
【问题描述】：

我希望在我的 Python 文档字符串中看到一些不错的语法高亮和着色，这些（当然）是有效的 REST。例如：

'''
A section
=========

an example::

    some code
'''
rest of python code

我得到的最接近的是我的.vim/after/syntax/python.vim：

syn include syntax/rst.vim 
syn region pythonDocstring  start=+^\s*'''+ end=+'''+ contained

根据the documentation of syntax-include 应该足够了。另请注意，rst.vim 重新定义了一堆 python 实体，所以我不得不注释掉所有与代码相关的部分：

" syn region rstCodeBlock contained matchgroup=rstDirective
"       \ start=+\%(sourcecode\|code\%(-block\)\=\)::\_s*\n\ze\z(\s\+\)+
"       \ skip=+^$+
"       \ end=+^\z1\@!+
"       \ contains=@NoSpell
" syn cluster rstDirectives add=rstCodeBlock

" if !exists('g:rst_syntax_code_list')
[...]

最后，我不能使用!runtime，因为如果b:current_syntax 变量已经定义，rst.vim 什么都不做：

if exists("b:current_syntax")
  finish
endif

尽管我努力了，但我的文档字符串与其他 cmets 保持相同的颜色，没有语法突出显示。

我也试过这个：

syn region pythonDocstring  start=+^\s*'''+ end=+'''+ contains=CONTAINED

但我只设法将块的颜色更改为 Special 而不是 Comment。

也许我应该将 pythonDocstring 定义为没有任何默认颜色？

进一步说明：如果我在 python.vim 中删除对 python 原始字符串的引用，着色会消失，但我只会突出显示 python 关键字。

更新

使用我的 after/syntax/python.vim 文件尝试以下解决方案之一：

syn include @pythonRst syntax/rst.vim 
syn region pythonDocstring  start=+^\s*'''+ end=+'''+ contains=@pythonRst

导致打开带有.py扩展名的文件时REST文件变灰：

使用.rst 打开同一个文件时。扩展似乎工作正常（只是为了表明我有一个休息语法文件）：

请注意，我在我的 .vimrc 中尝试了使用和不使用 colorscheme

【问题讨论】：

标签： python vim python-sphinx restructuredtext

【解决方案1】：

由于 reST 语法只能应用于内部 Python 文档字符串，因此您必须将它们包含在语法集群中（此处为：@pythonRst）。否则，Vim 会尝试在任何地方匹配它们。

syn include @pythonRst syntax/rst.vim

然后，定义一个覆盖这些文档字符串的区域，并明确指示 Vim 突出显示其中的 reST 语法（通过contains=）

syn region pythonDocstring  start=+^\s*'''+ end=+'''+ contains=@pythonRst

【讨论】：

我曾尝试过，但似乎没有奏效。我会发布一些图片作为更新。

【解决方案2】：

我终于成功破解了。

首先，我将 rst.vim 文件从 $VIMRUNTIME/syntax 复制到我的 .vim/syntax/ 文件夹中

其次，这是我的.vim/after/syntax/python.vim 文件（感谢@Ingo）：

syn include @pythonRst syntax/rst.vim 
syn region pythonDocstring  start=+^\s*"""+ end=+"""+ contains=@pythonRst

第三次我编辑了文件并注释掉这个块以忽略当前语法是否设置：

if exists("b:current_syntax")
  finish
endif

这个块加载代码插件（它导致了一些递归问题，因为它试图加载一个 python 语法文件，它加载了这个语法文件：

for code in g:rst_syntax_code_list
    unlet! b:current_syntax
[...]
   unlet! prior_isk
endfor

最后是这个块：

let b:current_syntax = "rst"

这样语法将保持为 python。

结果：

【讨论】：