Working example of floating image in reStructured Text

You can define a substitution:

.. |clearfloat|  raw:: html

    <div class="clearer"></div>

Then use the align attribute for images:

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

And insert a clearer like this:

|clearer|

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.

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.

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