0

According to the docs, an image should be displayable in the HTML-preview like so:

.. image:: /path/to/image.jpg

Yet, on VS Code version 1.56.2 on Windows 10 with the reStructuredTest - extension, the HTML-preview doesn't show the real picture, but only placeholders. I tried it with both UNIX- and Windows-like paths:

Image does not display in RST-files

The code I used is:

...
4) ...
5) .. image:: C:\Users\andreas.luckert\Downloads\Step-Functions-page1.png
6) .. image:: /c/Users/andreas.luckert/Downloads/Step-Functions-page2.png
rioV8
  • 24,506
  • 3
  • 32
  • 49
Andreas L.
  • 3,239
  • 5
  • 26
  • 65
  • While you got guidance below, any issue with that extension should be reported to https://github.com/vscode-restructuredtext/vscode-restructuredtext/issues I don't monitor questions like this on Stack Overflow. – Lex Li Dec 14 '22 at 07:12

1 Answers1

1

The link you provided is not to the official Sphinx docs, but a wiki page. Here are the docs for handling images.

reST supports an image directive (ref), used like so:

.. image:: gnu.png
    (options)

When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.

Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the _static directory for HTML output.)

So put your images in a directory named _static inside your top source directory, then update the relative path to the images as follows.

.. image:: _static/path/to/my-image.png
    (options)
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • In the bottom panel of VS Code it states `> Use docutils`. I'm not sure whether this implies `sphinx`. What's more, when I click on it, an error message pops up in the buttom right saying `Running the contributed command: 'restructuredtext.resetStatus' failed.`. – Andreas L. Jun 10 '21 at 06:50
  • Sphinx uses docutils, which processes reStructuredText to other formats. Sphinx adds features to that core. – Steve Piercy Jun 11 '21 at 05:21
  • I've just created a `_static` folder in my top directory, but don't know how to "rebuild my docs". As of yet, the picture does not get displayed in the HTML-preview; also not after restarting VS-Code. – Andreas L. Jun 14 '21 at 12:56
  • Re/build your docs. It's the same thing. You might need to `make clean` to remove cached files. – Steve Piercy Jun 15 '21 at 13:57
  • I looked it up in `StackOverFlow`, they also mention `make clean` and/or `make html`, but no one tells WHERE to execute these commands. If I enter it into PowerShell or bash, nothing happens and it is also not combinable with `sphinx-build`: https://stackoverflow.com/questions/21019505/sphinx-force-rebuild-of-html-including-autodoc – Andreas L. Jun 15 '21 at 14:20
  • 1
    Did you update the page to the image, e.g., `_static/gnu.png`? Otherwise, I don't use VS Code and I don't know what its preview feature supports. To build docs, you would need to install Sphinx. – Steve Piercy Jun 15 '21 at 15:13
  • Finally, this was the information I needed: `.. image:: _static/image-basename.png` makes all the magic happen after having created the `_static` folder in the root-directory where my `.rst`-file is located. @Steve could you please add this crucial part in your answer that on needs to add `_static` in front of the image name to make it work and that also on `Windows 10` one needs to use forward slashes `/` to make paths recognizable to `sphinx`? Once you've updated your answer with all these details, I'm gonna upvote and accept the answer. Thanks :) – Andreas L. Jun 15 '21 at 15:54