Working example of floating image in reStructured Text

Question

I'm looking for the best way to have an image with text appearing beside it in reStructured Text. I have found several sites purporting to show how it's done but none show an actual functioning example. Several show what appear to be failing examples. I'm actually working with Sphinx (v0.6.6) and hoping to avoid perverting the "native" CSS that comes with it more than necessary.

Answer 1

In the words of Emily Litella (of SNL), "Oh... Never mind..." ;-) And in the words of Alex Trebek (of Jepordy!) "And the answer is..."

In the .rst file

.. container:: twocol

   .. container:: leftside

      .. figure:: _static/illustrations/structure.svg

   .. container:: rightside

      Bla-bla-blah, and yada-yada.

In the custom CSS (I used a copy of sphinxdoc.css which I put in ./source/_static/):

div.leftside {
    width: 414px;
    padding: 0px 3px 0px 0px;
    float: left;
}

div.rightside {
    margin-left: 425px;
}

Each ..container:: becomes a <div>. In my case, I wanted a fixed width for the image and a variable width for the remainder. And, with a wee bit o' tweaking of the LaTeX produced by Sphinx, it also did a decent job of producing two-column output for that section.

I hope that's enough to help someone else figure out what wasn't obvious to me at first.

Answer 2

Working with Sphinx v1.1.3, I've been using the following method - a floating left image and a clearing block. It doesn't appear to be documented anywhere, and it's a bit hacky, so sharing here...

First the image, aligned left as per this rST doc.

.. image:: _static/my_image.png
     :align: left

Then you can write your paragraphs in the normal way, they wrap around the image.

When you're done, drop in a dirty clearer - I've used a 1x1 png as content for the container.

.. container:: clearer

    .. image :: _static/spacer.png

This generates the following HTML, which makes use of Sphinx's div.clearer CSS.

<div class="clearer container">
    <img src="_images/spacer.png" alt="_images/spacer.png">
</div>

Then you can carry on writing, with your next paragraph nicely cleared.

Answer 3

I think that a better result could be achieved using 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