Adding background color of notes to Sphinx-generated PDF files?

Question

I am able to generate notes using the Sphinx directive .. notes::. However, the notes in html file have a background color while those from the generated PDF don’t.

How can I add color to Sphinx-generated PDF files?

Answer 1

You can add something like this in your conf.py file (see the doc for the options for the LaTeX output):

latex_custom = r'''
\definecolor{Admonition}{RGB}{221,233,239}

\makeatletter
  \newenvironment{admonitionbox}{
    \begin{lrbox}{\@tempboxa}\begin{minipage}{\columnwidth}
  }{
    \end{minipage}\end{lrbox}
    \colorbox{Admonition}{\usebox{\@tempboxa}}
  }

  \renewenvironment{notice}[2]{
    \begin{admonitionbox}
  }{
    \end{admonitionbox}
  }
\makeatother
'''

latex_elements = {'preamble': latex_custom}

This is a basic example, it will change the background color of all the admonitions boxes (note, warning, tip, etc.).

Answer 2

My solution is inspired by the Nicolas' answer. It is built on top of the original sphinx code found in ./_build/latex/sphinx.sty. In contrast to Nicolas' solution, this one preserves the original Sphinx layout (spacings, frames, etc.) and adds the background color to it. Additionally, it differently treats lightbox (note, hint, tip, important) and heavybox (warning, caution, attention, danger, error) admonition box styles.

Add the following piece of code in your conf.py file (the final output should look something like this):

latex_custom = r'''
\definecolor{AdmonitionHeavyColor}{RGB}{255,204,204}
\definecolor{AdmonitionLightColor}{RGB}{238,238,238}

\makeatletter

  \renewcommand{\py@heavybox}{
    \setlength{\fboxrule}{1pt}
    \setlength{\fboxsep}{6pt}
    \setlength{\py@noticelength}{\linewidth}
    \addtolength{\py@noticelength}{-4\fboxsep}
    \addtolength{\py@noticelength}{-2\fboxrule}
    %\setlength{\shadowsize}{3pt}
    \Sbox
    \minipage{\py@noticelength}
  }

  \renewcommand{\py@endheavybox}{
    \endminipage
    \endSbox
    \savebox{\@tempboxa}{\fbox{\TheSbox}}
    \colorbox{AdmonitionHeavyColor}{\usebox{\@tempboxa}}
  }

  \renewcommand{\py@lightbox}{
    {%
      \setlength\parskip{0pt}\par
      \noindent\rule[0ex]{\linewidth}{0.5pt}%
      %\par\noindent\vspace{-0.2ex}%
    }
    \setlength{\py@noticelength}{\linewidth}
    \setlength{\fboxrule}{0pt}
    \setlength{\fboxsep}{2pt}
    %\setlength{\py@noticelength}{\linewidth}
    \addtolength{\py@noticelength}{-4\fboxsep}
    \addtolength{\py@noticelength}{-2\fboxrule}
    \Sbox
    \minipage{\py@noticelength}
  }

  \renewcommand{\py@endlightbox}{
    \endminipage
    \endSbox
    \savebox{\@tempboxa}{\fbox{\TheSbox}}
    \colorbox{AdmonitionLightColor}{\usebox{\@tempboxa}}
    {%
      \setlength{\parskip}{0pt}%
      \par\noindent\rule[0.5ex]{\linewidth}{0.5pt}%
      \par\vspace{-0.5ex}%
    }
  }


\makeatother
'''


latex_elements = {'preamble': latex_custom}

Answer 3

In more recent versions you can use the sphinx_setup key of latex_elements in your conf.py to achieve this for some admonitions rather easily, so something like:

latex_elements = {
    'sphinxsetup': 'warningBgColor={RGB}{255,204,204}'
}

Would change the warning background color to red. Check out the documentation for more info.

As of writing noteBgColor doesn't seem to be an option so this wouldn't help specifically for what was in the OP but could help for other admonitions.

Answer 4

Use latex if then else to create different colored boxes for different admonitions. Add this to the conf.py

latex_custom = r'''
    \makeatletter
    \usepackage{ifthen}
    \usepackage{tcolorbox}
    \tcbuselibrary{skins}
    \renewenvironment{sphinxadmonition}[2]
    {
       %Green colored box for Conditions
       \ifthenelse{\equal{#2}{Conditions}}{
                         \medskip
                         \begin{tcolorbox}[before={}, enhanced, colback=green!10, 
                                           colframe=green!65!black,fonttitle=\bfseries,
                                           title=\sphinxstrong{#2}, arc=0mm, drop fuzzy shadow=blue!50!black!50!white]}{

           %Blue colored box for Notes
           \ifthenelse{\equal{#2}{Note:}}{
                             \medskip
                             \begin{tcolorbox}[before={}, enhanced, colback=blue!5!white, 
                                               colframe=blue!75!black,fonttitle=\bfseries,
                                               title=\sphinxstrong{#2}, arc=0mm, drop fuzzy shadow=blue!50!black!50!white]}{
               %Orange colored box for Warnings 
               \ifthenelse{\equal{#2}{Warning:}}{
                             \medskip
                             \begin{tcolorbox}[before={}, enhanced, colback=orange!5!white, 
                                               colframe=orange!75!black,fonttitle=\bfseries,
                                               title=\sphinxstrong{#2}, arc=0mm, drop fuzzy shadow=blue!50!black!50!white]}{

                   %Red colored box for everthing else
                   \medskip
                   \begin{tcolorbox}[before={}, enhanced, colback=red!5!white, 
                                 colframe=red!75!black, fonttitle=\bfseries,
                                 title=\sphinxstrong{#2}, arc=0mm, drop fuzzy shadow=blue!50!black!50!white]}
           }
       }
    }
    {
       \end{tcolorbox}\par\bigskip
    } 

    \makeatother
'''

latex_elements['preamble'] += latex_custom

The output is something like this