Sphinx格式文档字符串在VSCode中渲染异常，是语法还是工具问题？

你编写的Sphinx格式Python函数文档字符串如下：

def test(foo):
    """this is my function
    
    .. code-block:: python
        cool function
    
    now I should be outside the codeblock. 
    But I'm not?
    
    .. code-block:: python
        next function
        
    I'm still inside the original codeblock?

    :param foo: _description_
    :type foo: _type_
    """

在VSCode中渲染时出现异常，后续文本被错误识别为代码块内容，这是你的语法编写有误，并非VSCode的渲染问题。

错误原因 #

Sphinx的.. code-block:: python指令有明确的缩进规则：

• 代码块内的内容必须比.. code-block:: python这一行多缩进至少4个空格
• 结束代码块时，后续文本需要回到和.. code-block:: python相同的缩进级别

你当前的代码块内容（cool function、next function）和指令行的缩进一致，导致Sphinx无法正确识别代码块的结束位置，后续所有文本都被误判为代码块的一部分。

修正后的代码 #

def test(foo):
    """this is my function
    
    .. code-block:: python
        # 比上一行多缩进4个空格
        cool function
    
    now I should be outside the codeblock. 
    I'm now correctly outside!
    
    .. code-block:: python
        # 同样多缩进4个空格
        next function
        
    I'm now outside the second codeblock too!

    :param foo: _description_
    :type foo: _type_
    """

修正后，VSCode就能正确区分代码块和普通文本，渲染效果会符合预期。

内容的提问来源于stack exchange，提问作者Martin