21

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Ubuntourist
  • 775
  • 11
  • 26

5 Answers5

12

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.

Ubuntourist
  • 775
  • 11
  • 26
  • Thank you very much. I was able to use the same technique (container and CSS) to make a paragrpah of text float next to the main body of text just like an image. – David C. Jun 11 '20 at 15:48
9

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.

jamesc
  • 5,852
  • 3
  • 32
  • 42
  • 1
    Have you found a way to do this for figures? http://stackoverflow.com/questions/16463051/how-to-create-floating-figures-in-restructuredtext-sphinx – Daniel May 09 '13 at 13:37
  • @dmd No I haven't used figures - but maybe a similar technique might work? – jamesc May 09 '13 at 13:53
  • Nope No luck with that. :( – Daniel May 09 '13 at 13:56
  • 1
    There is a slightly less hacky solution : define a substitution as raw::html
    . This removes the need for a dummy image     – galinette Sep 01 '15 at 16:02
  • actually there is no need for a dummy image. An empty comment is enough to mimic @galinette substitution – Francesco Montesano May 19 '16 at 21:08
  • 2
    The "clearer" style is not part of every theme. It is part of several bundled themes (nonav, agogo, epub, traditional and basic), but it is not (for example) part of the third-party RTD theme. If it's missing, you may have to add it to your CSS. – David C. Jun 16 '20 at 20:19
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

vinnie
  • 189
  • 1
  • 5
  • 1
    While this link may answer the question, it is better to include the essential parts of the answer here and provide the link for reference. Link-only answers can become invalid if the linked page changes. – Joel Oct 04 '13 at 16:11
  • 1
    I edited the answer adding an example of using substitutions. Thank you for pointing that out – vinnie Oct 04 '13 at 19:40
  • That's a completely different thing: You're embedding a small-ish image inline. (I knew how to do that.) I wanted a much bigger image in a two-column layout. (At least, I think that's what I wanted three years ago.) – Ubuntourist Dec 13 '13 at 18:38
  • Well... your question states "I'm looking for the best way to have an image with text appearing beside it in reStructured Text" and you're not specifying dimensions or layouts. Anyway if you take a look at the link I posted you can find MANY ways to achieve your goals. A substitution made with "image::" directives can be very helpful for a lot of usecases. I guess, you didn't clicked on the link provided by me maybe assuming that the small example reported was the only thing in there? A useful part of it is also: http://docutils.sourceforge.net/docs/ref/rst/directives.html#image – vinnie Mar 07 '14 at 16:29
2

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|
galinette
  • 8,896
  • 2
  • 36
  • 87
  • 2
    1. You first define `|clearfloat|` and than use `|clearer|`. 2. You omitted the CSS for `.clearer` – moi Sep 30 '19 at 19:47
0

you can just use a figure element like this:

.. figure: path/to/image.png
   :figwidth: 100%
   :target: images/navegacion_d.png

and the figure element will use the 100% of the body without changeing the original image width:

+---------------------------+
|        figure             |
|                           |
|<------ figwidth --------->|
|                           |
|  +---------------------+  |
|  |     image           |  |
|  |                     |  |
|  |<--- width --------->|  |
|  +---------------------+  |
|                           |
|The figure's caption should|
|wrap at this width.        |
+---------------------------+
Richard Mérida
  • 1