How do I display an image in Sphinx docs from a Python docstring?

Question

Python Docstring Image Embed

In a Python docstring I have a reStructuredText directive to display an image:

.. image:: ./images/code_quality.png

Instead of the image, I get a small icon and a path:

_images/code_quality.png

Screen clip of link shown instead of the image I want to show.

I have tried this also:

.. image:: images/code_quality.png

And this:

.. image:: https://imgs.xkcd.com/comics/code_quality.png
   :alt: code_quality

Using figure instead of image simply centers the same output.

.. figure:: images/code_quality.png

It also doesn't work if I take it out of the docstring and put it in an.rst file instead.

The image is copied into the _static directory as it should be by Sphinx. Any other formation of the link throws an error. I have two empty lines before and after the directive.

All other docstrings render correctly, including the rest of the docstring that contains the image link. I have no other images to render, but I did try this once before in another module and it did not work then either.

I'm using autodoc to scan the Python modules' docstrings. I am on Windows 10 and Chrome is my primary browser. It does not work on any other browsers I've tried either.

---

There are suggestions to look at this answer: Is it possible embed pictures into docstring in Python?

• I am using the image directive.
• My path is correct.
• Neither the relative path nor the full path lead to a rendered image.
• I am not using PyCharm for this project, I am using VS Code.
• My documentation renders fine apart from the image issue.

---

Shell output on make:

\docs>make html
Running Sphinx v2.4.4
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] user_guide
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] user_guide
generating indices...  genindex py-modindexdone
writing additional pages...  searchdone
copying images... [100%] images/code_quality.png
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

---

The image portion of the HTML output is:

<img alt="_images/code_quality.png" tedc="_images/code_quality.png" />

('tedc' is the name of the app as I defined it in the project's root setup.py module.)

---

GitHub Repo

This is my attempt to recreate the issue of image directives not working properly in Sphinx by creating a project that is structured the same general way my production project is structured.

My production code is called from root, with modules living in packages.

My documentation lives in a docs directory, the same as presented here.

I use a virtual environment, same as here.

I use a great many more libraries than are used here.

I'm using Python 3.8.2

I found nothing in the exercise that would help explain why the image directives are not working in my production code. My production code uses the same directives.

Answer 1

After I tried to reproduce this issue and failed to do so, I suggested that the OP should try deleting the virtual environment and docs build directory, and recreate their virtual environment, install requirements, and build docs again. This resolved the issue.