在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

根据语法包括的文档，这应该足够了。 另请注意， 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

尽管经过我的努力，我的文档字符串仍然与其他注释保持相同的颜色，并且没有突出显示语法。

我也试过这个：

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打开相同的文件。 扩展似乎可以正常工作（只是为了表明我有一个rest语法文件）：

请注意，我既没有试图colorscheme在我的.vimrc

Answer 1

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

syn include @pythonRst syntax/rst.vim

然后，定义一个覆盖这些文档字符串的区域，并明确指示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。

结果：