pythonpython-sphinxsphinx-napoleon

Insert image in sphinx using napoleon pre-processor


Using sphinx 3.1.1, I want to insert an image using the napoleon pre-processor.

It seems that by having the command: ".. image::" in the docstring, it prevents pre-interpretation with the napoleon pre-processor and the docstring is interpreted by the standard sphinx interpreter.

"""Func

   Args:
       var1 (number): description 1.
       var2 (string): description 2.

   Returns:
       string: description 3.

.. image:: /_images/test.png
   :width: 100
"""

My image is correctly visualized, but parameters and return values are not correctly interpreted, they look like plain text.

enter image description here

When I remove the image command, I get the expected interpretation:

"""Func

   Args:
       var1 (number): description 1.
       var2 (string): description 2.

   Returns:
       string: description 3.
"""

enter image description here

Does anyone have a solution?

Remark: I don't want to write my documentation in sphinx standard reStructuredText.


Solution

  • Whitespace is important. The image directive must be aligned with the other paragraphs in the docstring.

    It can look like this:

    """Func
    
       Args:
           var1 (number): description 1.
           var2 (string): description 2.
    
       Returns:
           string: description 3.
    
       .. image:: /_images/test.png
          :width: 100
    """
    

    Or like this:

    """
    Func
     
    Args:
        var1 (number): description 1.
        var2 (string): description 2.
     
    Returns:
        string: description 3.
     
    .. image:: /_images/test.png
       :width: 100
    """