How to create floating figures in reStructuredText / Sphinx?

Question

I want to have a figure with text wrapped around it.

This is what I'm saying:

Installation of Optional Accessories
====================================

.. warning:: Never plug in or unplug a Hand Robot or a Grasp Sensor while the robot is turned on, as the system will not function properly and damage to the robot could occur.

Installing a Hand Robot
-----------------------

.. _`fig-attach-hand-robot`:
.. figure:: attach-hand-robot.*
  :scale: 40%
  :align: right

  Attach Hand Robot

Make sure the robot is turned off as described in the section :ref:`turn-off-robot`. 

Take the hand robot out of the grounded bin that sits on top of the electrical panel (if you have an adjustable height table) or sits on top of the rear table (if you have a fixed height table). Make sure not to touch the pins on the electrical wiring while doing so. Insert the conical protrusion of the hand robot into the conical receptacle (see :ref:`fig-attach-hand-robot`). Once the hand robot is supported by the InMotion Arm Robot, make sure the two knobs below the Hand Robot have engaged and sprung in. If they have not, twist them until they do as shown (see :ref:`fig-knobs-in`).

and this screenshot of PDF output is what I'm getting.

Why is the figure caption centered, rather than under the image?
Why isn't the body text ("Make sure ..." and "Take the ...") on the LEFT of the image, rather than underneath it? I want the figure to float right and have the text on its left.

score 7 · Answer 1 · answered Apr 23 '20 at 21:26

I have found that figures float to the side with :figwidth: and :align: specified. (Using the readthedocs theme.)

..  figure:: images/myimage.jpg
    :figwidth: 40%
    :align: right

https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure

score 6 · Accepted Answer · answered May 13 '13 at 16:01

So, I did some research into reStructuredText and it seems what you want is not actually possible.

The documentation for the figure and the image directives never mention the ability to wrap text around the object.

This might be a feature request to provide to the Sphinx developers although I suspect they'll reject it because it isn't explicitly mentioned in the rst specification.

I was hoping the bounty would garner this some attention but I suspect is hasn't.

score 6 · Answer 3 · edited Feb 12 '19 at 04:32

6

Though it is too late but maybe the answer would help future people.

You can use the sidebar directive to put the image.

.. sidebar:: mandatory_title. Use can use image caption here

     .. Figure:: 1.png

edited Feb 12 '19 at 04:32

Michael Kropat

14,557
12
70
91

answered Dec 21 '18 at 13:44

shubham

61
1
1

score 1 · Answer 4 · answered Oct 04 '13 at 19:47

1

In order to deal with images as they were part of the text you may actually use substitutions.

Here an extract from the documentation that can be helpful:

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

I hope this helps

answered Oct 04 '13 at 19:47

vinnie

189
1
5

This isn't very helpful if one needs to put a large illuminated letter at the beginning of a chapter. – Frotz Apr 07 '16 at 01:43

score 1 · Answer 5 · edited Nov 15 '15 at 13:08

If anyone else runs into this problem then this bit of code might be a help. I decided that I didn't want to hack the actual sphinx code so I made a very short python script applied to the generated _build/latex/pi3d_book.tex to convert the \includegraphics that had \hfill before or after into wrapped images. There will be lots of things that stop this working such as putting images inside lists or scaling images. The sphinx directives in my rst are like

.. image:: perspective.png
   :align: right

You obviously have to change the file names and paths to suit your setup. From my spinx project I run

$ make latexpdf
$ python wrapfix.py # or whatever you call this file

program listing of wrapfix.py

import subprocess

with open("_build/latex/pi3d_book.tex", "r") as f:
  tx = f.read().splitlines()

txnew = []
flg1 = True
for line in tx:
  if line == "" and flg1:
    txnew += ["\\usepackage{wrapfig}",""]
    flg1 = False # just do this once before first blank line
  elif "includegraphics{" in line and "hfill" in line:
    fname = line.split("{")[2].split("}")[0]
    if line.startswith("{\\hfill"): # i.e. right justify
      fl_type = "R"
    else:
      fl_type = "L"
    txnew += ["\\begin{wrapfigure}{" + fl_type + "}{0.35\\textwidth}",
              "\\includegraphics[width = 0.3\\textwidth]{" + fname + "}",
              "\\end{wrapfigure}"]
  else:
    txnew += [line]

txnew = "\n".join(txnew)
with open("_build/latex/pi3d_book.tex", "w") as fo:
  fo.write(txnew)

subprocess.Popen(["pdflatex", "pi3d_book"], cwd="/home/jill/pi3d_book/_build/latex")

I am trying to include an image in my Sphinx+Latex pdf file but coming up with errors. Could you check this [question](https://stackoverflow.com/questions/63452024/how-to-include-image-files-in-sphinx-latex-pdf-files) please? — shaan, Aug 18 '20 at 13:11

How to create floating figures in reStructuredText / Sphinx?

5 Answers5

Linked