Image of structured text (Sphinx) in title?

Question

Is it possible to place an image inside the title using restructured text?

Sort of:

Introduction .. image:: path/to/img.png --------------------------------------- 

This is displayed as text, i.e. image syntax is not parsed. I have not seen any examples of this, making me believe that it will be impossible, but maybe someone has a workaround.

I intend to output to HTML (so modifying the resulting CSS is possible, although I would prefer to change the source of RST. This is due to the fact that I also intend to output to pdf (latex).

Answer 1

With HTML and CSS, there are several ways to add an image to an element that produces different results. A couple I can think of is:

• Use an image instead of any text. Here we save the text, but send it from the screen, so it is still available.

   h1 { background: url(images/image.jpg) no-repeat top center; display: block; text-indent: 100%; white-space: nowrap; overflow: hidden; width: XXpx; height: XXpx; } 

• Place the image to the left of the text (or can be easily right)

   h1 { background: url(images/image.jpg) no-repeat top left; padding-left: XXpx; } 

• Use a background image, behind any text

   h1 { background:url(images/image.jpg) no-repeat top center; } 

More specific CSS selectors can only be used to target specific headers.

You can easily add custom CSS to reStructuredText documents using the raw directive , for example:

 .. raw:: html <style> <!-- One of the CSS styles above. --> </style> 

Alternatively, you can include your own CSS style sheets from the command line using the --stylesheet rst2html.py option.

In terms of achieving this with the release in PDF, I will steal part of another of my answer :

Obviously, the above goals output HTML. However, I did not use rst2pdf, so I can not comment on how you need to change this to work with this program. Hope someone else answers this. As far as I know, rst2pdf supports a cascading style sheet mechanism , so it should be simple (for those who know the rst2pdf style sheet syntax) to add an extra role .. raw:: pdf and change the list styles specified.

Answer 2

I think that a better result can be achieved using aliases (i.e. replacements ).

Here is an excerpt from the documentation that may be helpful:

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

hope this helps

Answer 3

This can be achieved using substitution in the header:

 Header Text |foo| ================= .. |foo| image:: path/to/img.png 

Here foo is just an example of the replacement text. It can be anything, but it should not begin or end with a space.

The syntax for abstract substitution is as follows:

 +-------+-----------------------------------------------------+ | ".. " | "|" substitution text "| " directive type "::" data | +-------+ directive block | | | +-----------------------------------------------------+ 

As we would like to insert an inline image, we must select image as a directive type .

Answer 4

Maybe try an alias (via a random web link): http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html#id28