2

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.

Community
  • 1
  • 1
jhachtel
  • 43
  • 9
  • Silly question, but is the path `./images/code_quality.png` correct? – John Palmieri Apr 27 '20 at 03:40
  • Duplicate of https://stackoverflow.com/questions/45739474/is-it-possible-embed-pictures-into-docstring-in-python – seanpue Apr 27 '20 at 04:07
  • Does this answer your question? [Is it possible embed pictures into docstring in Python?](https://stackoverflow.com/questions/45739474/is-it-possible-embed-pictures-into-docstring-in-python) – Steve Piercy Apr 27 '20 at 04:29
  • @JohnPalmieri: Yes, the path is correct. Both './' and no prefix seem to do the same thing for me. Sphinx finds the file and copies it, the image simply doesn't show up. the path is rendered with an underscore prefix. The same is hapening for profile pics I want to embed. – jhachtel Apr 28 '20 at 15:13
  • @seanpue: Thank you. It does appear that the other OP and I are having the same or a similar issue, but no, the solutions there do not work. – jhachtel Apr 28 '20 at 15:17
  • @StevePiercy: Thank you. It does appear that the other OP and I are having the same or a similar issue, but no, the solutions there do not work. – jhachtel Apr 28 '20 at 15:18
  • @jhachtel Did you try /images/code_quality.png? – seanpue Apr 28 '20 at 15:29
  • @seanpue: Yes. I did try without the '.' and without the './'. Using /images/code_quality.png or images/code_quality.png gives _images/code_quality.png as the visual output and saves the file internally as code_quality.png. – jhachtel Apr 28 '20 at 15:43
  • So the resulting html produced by Sphinx is wrong? What is wrong with it? – John Palmieri Apr 28 '20 at 15:50
  • @JohnPalmieri: I didn't think to look, so thank you for asking. Here is the html for the image as rendered by Sphinx. I'll put it in the body of the question as well. _images/code_quality.png – jhachtel Apr 28 '20 at 15:53
  • @JohnPalmieri: -FYI- 'tedc' is the name of the app I gave it in the root setup.py. – jhachtel Apr 28 '20 at 16:01
  • What's wrong with the html? What should it say instead? – John Palmieri Apr 28 '20 at 21:10
  • 1
    @jhachtel the `img` HTML tag lacks a `src` attribute, and `tedc` is not a valid HTML attribute for `img`. I have no idea how you got that HTML from the rst code you provided, and it should provide a `src` attribute. You must have a `src` attribute, else the image will not display. – Steve Piercy Apr 29 '20 at 03:37
  • If you want more than "stab in the dark" comments, you need to tell us exactly how to reproduce the problem. Please provide a [mcve]. – mzjn Apr 29 '20 at 07:29
  • @mzjn: I would love to tell you how to reproduce the problem - if I knew how to produce it. All I can do right now is report what I do know, which is what I've done. Maybe, add a tedc attribute to your image HTML, remove the src attribute and see if that does the same thing? – jhachtel Apr 29 '20 at 21:57
  • @StevePiercy: I don't know how that tedc attribute got there either. My guess is that it is being read from the setup.py module, but your comment gives me something to look for. Thank you. – jhachtel Apr 29 '20 at 21:59
  • @jhachtel to provide a minimal reproducible example, read the content at the link provided by mzjn, then give us code to review, such as through a public repository. – Steve Piercy Apr 29 '20 at 23:31
  • @StevePiercy: I'll try to get it done today. Again, I have no idea of the source of the issue, so reproducing it feels a lot like luck to me. I did a search of my project for 'tedc'. It shows up in my setup.py file as the name of the app, `name='tedc'`, and as part of a print string I output as part of the CLI in a module, and as parts of various strings in my rst files - none of which are settings of any kind or have anything to do with my images. Lastly, it shows up in a wsdl as accidental substrings, as in 'Lis*tedC*ount', or 'Trunca*tedC*ontent'. – jhachtel May 01 '20 at 13:03
  • @StevePiercy: Here is my public Github repo, demonstrating working and non-working image directives. I updated my post as well. If nothing else, it shows that I do know how to use them and that my system can implement them. I gained no insight from the exercise, however. https://github.com/jhachtel/sphinx-image-test – jhachtel May 01 '20 at 16:02
  • @mzjn: See the comment above. – jhachtel May 01 '20 at 16:02
  • @StevePiercy: This test project is rendering the src attribute in the html, while my production code is not. I think you found the break, but I still have no inkling of why it might be doing that. I'm going to try rebuilding Sphinx. I'll give an update later today. – jhachtel May 01 '20 at 16:10
  • @StevePiercy: Update of sphinx via `pip install -U sphinx` did not help, nor did a re-run of `sphinx-quickstart` after removing content files. 'tedc' still shows in the built html instead of 'src'. I wonder where that is being generated from? – jhachtel May 01 '20 at 16:59
  • I'm over my head on where sphinx decides not to write 'src' and instead write 'tedc', especially since the only place it could matter is the same in the prod and example projects. I've searched an looked through the sphinx source and am not seeing it. I'm pulling images from production and will worry about it another time. Thanks for all your help. What do I do with this post now? – jhachtel May 01 '20 at 18:15
  • 1
    I tried to reproduce it using your repo, but was not able to. I think that you are on to something with the `name='tedc'` in your `setup.py`. Your repo has it named `app`, but I did not see `app` instead of `src` for an image attribute. I have never seen anything like this. My only suggestion is to throw out your virtual environment and Sphinx build directory, and recreate your virtual environment, install requirements, and build docs again. – Steve Piercy May 02 '20 at 09:14
  • @StevePiercy: I'll give that a shot. Yes, I couldn't reproduce it either, except by puposefully giving a wrong path. I've got to do so cleanup on the project anyway, so rebuilding the environment, etc isn't a big deal. I'll let you know how it goes. – jhachtel May 03 '20 at 03:19
  • A couple of suggestions for organizing your project: (1) `/project-name` should be the root folder. (2) Put Python source files in `./src/project-name`. (3) Put docs stuff in `./docs`, with subdirectories of `src` for rst files, `src/_static` for static assets, and `_build` for docs build output. (4) Put tests in `./tests`. To see a real world example, check out [Pyramid](https://github.com/Pylons/pyramid/tree/master/docs). The only thing it does not do out of my suggestions is a subdirectory for `docs/src` and instead uses `docs` for source files, but you get the idea. – Steve Piercy May 03 '20 at 05:00
  • @StevePiercy: Thank you for the suggestions. I'll take a look and see how Pyramid is organized. – jhachtel May 04 '20 at 22:03
  • @StevePiercy: The suggestion to delete the sphinx build directory and virtual environment worked. Images display as expected now. I think that counts for an answer. I wish I knew what it was, specifically, that caused the issue, but I'm not sure that's a possibility. Thanks for all your help, Steve. – jhachtel May 04 '20 at 22:08

1 Answers1

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.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57