pythonvisual-studio-codepython-sphinxdocstring

sphinx docstrings and vscode


I have the following docstring:

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_
    """

Which renders like this in VScode:

enter image description here

Am I writing the syntax incorrectly, or does VScode simply struggle with the rendering of sphinx format?


Solution

  • There are two ways to get the display right

    1. Add a level of indentation for code blocks

    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_
        """
    

    enter image description here

    2. Remove one level of indentation for non-code blocks

    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_
        """
    

    enter image description here

    I'm not sure if this is the correct syntax, or if it's a vscode error. If anyone thinks it's an error, you can report it on GitHub and share the link here.