Sphinx Verbatim (Code block) with background color

Question

I would like to remove the frames and set a light grey shade background to my code blocks.

I know I could use colorbox such as \begin{tcolorbox}, but I have no idea where to place it.

Sphinx uses this environment:

\newenvironment{sphinxVerbatim}{%
  % first, let's check if there is a caption
  \ifx\sphinxVerbatimTitle\empty
      \sphinxvspacefixafterfrenchlists
      \parskip\z@skip
      \vskip\sphinxverbatimsmallskipamount
      % there was no caption. Check if nevertheless a label was set.
      \ifx\sphinxLiteralBlockLabel\empty\else
      % we require some space to be sure hyperlink target from \phantomsection
      % will not be separated from upcoming verbatim by a page break
          \needspace{\sphinxliteralblockwithoutcaptionneedspace}%
          \phantomsection\sphinxLiteralBlockLabel
      \fi
  \else
     \parskip\z@skip
     \if t\spx@opt@literalblockcappos
       \vskip\spx@abovecaptionskip
       \def\sphinxVerbatim@Before
           {\sphinxVerbatim@Title\nointerlineskip
            \kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace
                 % if no frame (code-blocks inside table cells), remove
                 % the "verbatimsep" whitespace from the top (better visually)
                 \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
                 % caption package adds \abovecaptionskip vspace, remove it
                 \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}%
     \else
       \vskip\sphinxverbatimsmallskipamount
       \def\sphinxVerbatim@After
          {\nointerlineskip\kern\dimexpr\dp\strutbox
            \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
            \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax
           \sphinxVerbatim@Title}%
     \fi
     \def\@captype{literalblock}%
     \capstart
     % \sphinxVerbatimTitle must reset color
     \setbox\sphinxVerbatim@TitleBox
            \hbox{\begin{minipage}{\linewidth}%
     % caption package may detect wrongly if top or bottom, so we help it
                    \spx@ifcaptionpackage
                      {\caption@setposition{\spx@opt@literalblockcappos}}{}%
                    \sphinxVerbatimTitle
                  \end{minipage}}%
  \fi
  \global\let\sphinxLiteralBlockLabel\empty
  \global\let\sphinxVerbatimTitle\empty
  \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
  \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi
  \let\FrameCommand     \sphinxVerbatim@FrameCommand
  \let\FirstFrameCommand\sphinxVerbatim@FirstFrameCommand
  \let\MidFrameCommand  \sphinxVerbatim@MidFrameCommand
  \let\LastFrameCommand \sphinxVerbatim@LastFrameCommand
  \ifspx@opt@verbatimhintsturnover\else
      \let\sphinxVerbatim@Continued\@empty
      \let\sphinxVerbatim@Continues\@empty
  \fi
  \ifspx@opt@verbatimwrapslines
  % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
  % This customization wraps each line from the input in a \vtop, thus
  % allowing it to wrap and display on two or more lines in the latex output.
  %     - The codeline counter will be increased only once.
  %     - The wrapped material will not break across pages, it is impossible
  %       to achieve this without extensive rewrite of fancyvrb.
  %     - The (not used in sphinx) obeytabs option to Verbatim is
  %       broken by this change (showtabs and tabspace work).
    \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineWrap
    \let\FV@Space\spx@verbatim@space
  % Allow breaks at special characters using \PYG... macros.
    \sphinxbreaksatspecials
  % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
    \fvset{codes*=\sphinxbreaksviaactive}%
  \else % end of conditional code for wrapping long code lines
    \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineNoWrap
  \fi
  \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
  \VerbatimEnvironment
  % workaround to fancyvrb's check of current list depth
  \def\@toodeep {\advance\@listdepth\@ne}%
  % The list environment is needed to control perfectly the vertical space.
  % Note: \OuterFrameSep used by framed.sty is later set to \topsep hence 0pt.
  % - if caption: distance from last text baseline to caption baseline is
  %   A+(B-F)+\ht\strutbox, A = \abovecaptionskip (default 10pt), B =
  %   \baselineskip, F is the framed.sty \FrameHeightAdjust macro, default 6pt.
  %   Formula valid for F < 10pt.
  % - distance of baseline of caption to top of frame is like for tables:
  %   \sphinxbelowcaptionspace (=0.5\baselineskip)
  % - if no caption: distance of last text baseline to code frame is S+(B-F),
  %   with S = \sphinxverbatimtopskip (=\smallskip)
  % - and distance from bottom of frame to next text baseline is
  %   \baselineskip+\parskip.
  % The \trivlist is used to avoid possible "too deeply nested" error.
  \itemsep   \z@skip
  \topsep    \z@skip
  \partopsep \z@skip
  % trivlist will set \parsep to \parskip = zero
  % \leftmargin will be set to zero by trivlist
  \rightmargin\z@
  \parindent  \z@% becomes \itemindent. Default zero, but perhaps overwritten.
  \trivlist\item\relax
     \ifsphinxverbatimwithminipage\spx@inframedtrue\fi
     % use a minipage if we are already inside a framed environment
     \ifspx@inframed\noindent\begin{minipage}{\linewidth}\fi
     \MakeFramed {% adapted over from framed.sty's snugshade environment
        \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
        }%
     % For grid placement from \strut's in \FancyVerbFormatLine
     \lineskip\z@skip
     % active comma should not be overwritten by \@noligs
     \ifspx@opt@verbatimwrapslines
       \let\verbatim@nolig@list \sphinx@verbatim@nolig@list
     \fi
     % will fetch its optional arguments if any
     \OriginalVerbatim
}

Answer 1

It looks like you should be able to edit the frames and background color of code blocks through Sphinx configuration rather than messing around with the TeX files. This link has some good information about this:

https://www.sphinx-doc.org/en/master/latex.html

Specifically, the "verbatimwithframe," the "VerbatimColor," and the "VerbatimBorderColor" elements seem to be relevant to your issue.

EDIT:

After playing around with this a little bit, adding:

# conf.py
latex_elements = {
   "sphinxsetup": 'verbatimwithframe=false, VerbatimColor={gray}{0.95}',
}

into the latex_elements field of your conf.py file in the Sphinx project will allow you to change the background color of verbatim blocks.