为 Sphinx 生成的 PDF 文件添加注释的背景颜色？

Question

我可以使用 Sphinx 指令生成笔记

.. notes::

。但是，html 文件中的注释具有背景色，而生成的 PDF 中的注释则没有。

如何为 Sphinx 生成的 PDF 文件添加颜色？

Answer 1

您可以在

conf.py

文件中添加这样的内容（有关 LaTeX 输出的选项，请参阅 doc）：

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}

这是一个基本的例子，它将改变所有告诫框（注意、警告、提示等）的背景颜色。

Answer 2

我的解决方案是受到 Nicolas 的回答的启发。它建立在

./_build/latex/sphinx.sty

中的原始 sphinx 代码之上。与 Nicolas 的解决方案相反，此解决方案保留了原始的 Sphinx 布局（间距、框架等）并为其添加了背景颜色。此外，它以不同方式对待

lightbox

（注意、提示、提示、重要）和

heavybox

（警告、警告、注意、危险、错误）警告框样式。

在您的

conf.py

文件中添加以下代码 （最终输出应该类似于）：

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

在较新的版本中，您可以在

sphinx_setup

中使用

latex_elements

的

conf.py

键来轻松实现some告诫，例如：

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

将警告背景颜色更改为红色。查看文档了解更多信息。

在写作时

noteBgColor

似乎不是一个选择，所以这对 OP 中的内容没有特别帮助，但可以帮助其他警告。

Answer 4

使用 latex if then else 为不同的告诫创建不同颜色的框。将此添加到

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

输出是这样的

Answer 5

我注意到错误：

\label #1->@bsphack egingroup \def \label@name

{#1}\label@hook\protected... l.709 ...el{\detokenize{file1:id1}}Todo:}

在使用此 ifelsethen 代码时。