1

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.

Worldsheep
  • 163
  • 3
  • 1
    please show the the image of the error – Yagav Jul 01 '20 at 12:21
  • 1
    Please show the text of the error message (please no images of text) by editing your question, as well as the portion of the docstring that throws the error message. – Steve Piercy Jul 01 '20 at 17:53
  • 1
    Done! I hope it is clearer now :). Actually no error involved, just the napoleon pre-processor stop working. – Worldsheep Jul 02 '20 at 15:41

1 Answers1

1

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
"""
mzjn
  • 48,958
  • 13
  • 128
  • 248