How to customize an existing LaTeX environment without interfering with other environments

Question

I'm using Sphinx for documenting a project. It produces LaTeX files from restructured text.

I would like to set a gray background color to the tips and notes, so I customized the notice environment after creating a graybox environment:

\definecolor{MyGray}{rgb}{0.80,0.80,0.80}

\makeatletter\newenvironment{graybox}{%
   \begin{lrbox}{\@tempboxa}\begin{minipage}{\columnwidth}}{\end{minipage}\end{lrbox}%
   \colorbox{MyGray}{\usebox{\@tempboxa}}
}\makeatother

\makeatletter
\renewenvironment{notice}[2]{
  \begin{graybox}
  \bf\it
  \def\py@noticetype{#1}
  \par\strong{#2}
  \csname py@noticestart@#1\endcsname
}
{
  \csname py@noticeend@\py@noticetype\endcsname
  \end{graybox}
}
\makeatother

Everything works fine except if I place a figure environment inside the notice environment. In that case, I get this error:

LaTeX Error: Not in outer par mode

Is there a way to set a gray background to that notice environment ?

Answer 1

This is a FAQ. It does not make sense to put a figure (or any other "float" which can move elsewhere in the output) inside a gray box; if you want your figure to contain a gray box, put the gray box environment inside the figure environment.

Answer 2

As Jouni correctly pointed out, figures and tables (i.e., floats) can be moved around, and your gray box can't contain them. To achieve the desired effect, you have two options:

1. Put your entire notice into a figure environment (so that the entire notice can be floated around on the page or to a new page if LaTeX so chooses).

2. Don't use a float (figure environment) -- just use \includegraphics to pop your image directly into the notice environment. You won't be able to use a caption with this non-figure, however, as captions only work inside a figure or table environment. If you want a caption associated with this image, you can use the caption package:

   \documentclass{article}
   \usepackage{caption}% let's us use captions outside of floats
   \usepackage{lipsum}% provides filler text
   \begin{document}
   \lipsum[1]
   \begin{center}
     \includegraphics{mypic}
     \captionof{figure}{This is my picture.}% makes a caption for non-floats
     \label{fig:mypic}
   \end{center}
   \lipsum[2]        
   \end{document}
   

I haven't used Sphinx, so I'm afraid I can't help you too much with integrating this into their output.

Answer 3

Thank you godbyk and Jouni for answering my question.

The problem is that I don't code directly in LaTeX. I write the documentation in restructured text and Sphinx output the LaTeX files.

But I found a solution: I redefine the figure environment to use the staticfigure from the flowfram package:

\usepackage{flowfram}

\definecolor{MyGray}{rgb}{0.80,0.80,0.80}

\makeatletter\newenvironment{graybox}{%
   \begin{lrbox}{\@tempboxa}\begin{minipage}{\columnwidth}}{\end{minipage}\end{lrbox}%
   \colorbox{MyGray}{\usebox{\@tempboxa}}
}\makeatother

\makeatletter
\renewenvironment{notice}[2]{
  \begin{graybox}
  \bf\it
  \def\py@noticetype{#1}
  \par\strong{#2}
  \csname py@noticestart@#1\endcsname
}
{
  \csname py@noticeend@\py@noticetype\endcsname
  \end{graybox}
}
\makeatother

\renewenvironment{figure}[6]{
  \begin{staticfigure}
}{
  \end{staticfigure}
}

PS: I had to put 6 to the number of arguments when redefining 'figure': if I don't do that it outputs some 'htbp' in the pdf files (I'm not a LaTeX expert. it's just the solution I found for this problem)