Question

I currently use Sphinx to generate LaTeX output which is turned into a PDF for book-style output using pdftex.

Currently, I have notices, warnings, and other “admonitions” showing up inside a bounded box, in a style that looks a little like this:

-----------------------------------
| Warning:     lorem ipsum foozle |
|  fuzzle fuzz buzz               |
|----------------------------------

The LaTeX that generates such a box looks like this:

\begin{notice}{warning}{Warning:}
The \code{repoze.bfg} documentation is offered under the
Creative Commons Attribution-Nonconmmercial-Share Alike 3.0 United
States License.
\end{notice}

There are a series of commands in a LaTeX .sty file that provide the box
behavior:

% Notices / Admonitions
%
\newlength{\py@noticelength}

\newcommand{\py@heavybox}{
\setlength{\fboxrule}{1pt}
\setlength{\fboxsep}{7pt}
\setlength{\py@noticelength}{\linewidth}
\addtolength{\py@noticelength}{-2\fboxsep}
\addtolength{\py@noticelength}{-2\fboxrule}
\setlength{\shadowsize}{3pt}
\Sbox
\minipage{\py@noticelength}
}
\newcommand{\py@endheavybox}{
\endminipage
\endSbox
\fbox{\TheSbox}
}

% Some are quite plain:
\newcommand{\py@noticestart@note}{}
\newcommand{\py@noticeend@note}{}
\newcommand{\py@noticestart@hint}{}
\newcommand{\py@noticeend@hint}{}
\newcommand{\py@noticestart@important}{}
\newcommand{\py@noticeend@important}{}
\newcommand{\py@noticestart@tip}{}
\newcommand{\py@noticeend@tip}{}

% Others gets more visible distinction:
\newcommand{\py@noticestart@warning}{\py@heavybox}
\newcommand{\py@noticeend@warning}{\py@endheavybox}
\newcommand{\py@noticestart@caution}{\py@heavybox}
\newcommand{\py@noticeend@caution}{\py@endheavybox}
\newcommand{\py@noticestart@attention}{\py@heavybox}
\newcommand{\py@noticeend@attention}{\py@endheavybox}
\newcommand{\py@noticestart@danger}{\py@heavybox}
\newcommand{\py@noticeend@danger}{\py@endheavybox}
\newcommand{\py@noticestart@error}{\py@heavybox}
\newcommand{\py@noticeend@error}{\py@endheavybox}

\newenvironment{notice}[2]{
  \def\py@noticetype{#1}
  \csname py@noticestart@#1\endcsname
  \par\strong{#2}
}{\csname py@noticeend@\py@noticetype\endcsname}

Instead of just having a box around the notice and having a word represent the type of notice inside the box, I’d like to retain the box around the admonitition, but replace the word “warning” in the box with an image, like so:

-------------------------------------------
|    ---                                  |
|   /   \                                 |
|   \   /                                 |
|    ---    Fuzzle foo buz lorem ipsum    |
-------------------------------------------

I cannot change the \begin{notice} … \end{notice} latex literals rendered by Sphinx (well, I can, but it’s a real pain in the ass). I’d prefer to just put the logic in a new \newenvironment{notice} macro. Can anyone recommend a strategy? Everything I’ve tried so far has ended in tears.

Answer 1

Try the following (which requires the ifthen or xifthen package for the \ifthenelse command):

% Keep a copy of the original notice environment
\let\origbeginnotice\notice
\let\origendnotice\endnotice

% Redefine the notice environment so we can add our own code to it
\renewenvironment{notice}[2]{%
  \origbeginnotice{#1}{#2}% equivalent to original \begin{notice}{#1}{#2}
  % load graphics
  \ifthenelse{\equal{#1}{warning}}{\includegraphics{warning}}{}
  \ifthenelse{\equal{#1}{notice}}{\includegraphics{notice}}{}
  % etc.
}{%
  \origendnotice% equivalent to original \end{notice}
}

You’ll have to find a way to get this code into the preamble of the document.