在Python文档字符串中嵌入reStructuredText

Question

我希望在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，因为如果rst.vim变量已定义，则b:current_syntax不执行任何操作：

if exists("b:current_syntax")
  finish
endif

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

我也试过这个：

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进行了尝试

Answer 1

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

syn include @pythonRst syntax/rst.vim

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

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

Answer 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。

结果：