在 Python 文档字符串中嵌入 reStructuredText [英] Embedding reStructuredText in Python docstrings

问题描述

我希望在我的 Python 文档字符串中看到一些不错的语法突出显示和着色(当然)是有效的 REST.例如:

'''一节==========一个例子::一些代码'''其余的python代码

在我的 .vim/after/syntax/python.vim 中，最接近的是这个:

syn 包含语法/rst.vimsyn region pythonDocstring start=+^\s*'''+ end=+'''+ 包含

根据

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

请注意，我已经在我的 .vimrc

中尝试过使用和不使用 colorscheme

解决方案

由于 reST 语法只应应用于 inside Python 文档字符串，您必须将它们包含到语法集群中(此处:<代码>@pythonRst).否则，Vim 会尝试在任何地方匹配它们.

syn 包含@pythonRst 语法/rst.vim

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

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

I'd like to see some nice syntax highlighting and colouring in my Python's docstrings which (of course) are valid RESt. For example:

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

an example::

    some code
'''
rest of python code

The closest I've got is this in my .vim/after/syntax/python.vim:

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

According to the documentation of syntax-include that should be sufficient to. Also note that rst.vim re-defines a bunch of python entities so I've had to comment out all sections related to code:

" 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')
[...]

Lastly, I can't use !runtime because rst.vim does nothing if the b:current_syntax variable is already defined:

if exists("b:current_syntax")
  finish
endif

Despite my efforts my docstring stays the same colour as other comments, with no syntax highlighting.

I've tried also this:

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

But I only managed to change the colour of the block to be Special rather than Comment.

Perhaps I should define the pythonDocstring not to have any default colouring?

Further note: if I remove references to python raw strings in python.vim, colouring disappears but I only get the python keywords highlighted.

---

Update

Trying one of the solutions below with my after/syntax/python.vim file:

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

Resulted in the RESt file being grayed out when opening a file with .py extension:

While opening the same file with a .rst. extension seems to work fine (just to show that I have a rest syntax file):

Note that I've tried both with and without colorscheme in my .vimrc

解决方案

As the reST syntax should only be applied inside Python doc strings, you have to include them into a syntax cluster (here: @pythonRst). Otherwise, Vim would try to match them everywhere.

syn include @pythonRst syntax/rst.vim

Then, define a region covering those doc strings, and explicitly instruct Vim to highlight reST syntax in there (via contains=)

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

这篇关于在 Python 文档字符串中嵌入 reStructuredText的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！