Expose some sphinx.sty LaTeX internals for customizability (refs: #4285)

CHANGES

@@ -16,6 +16,7 @@ Features added
 * #4181: autodoc: Sort dictionary keys when possible
 * ``VerbatimHighlightColor`` is a new
   :ref:`LaTeX 'sphinxsetup' <latexsphinxsetup>` key (refs: #4285)
+* Easier customizability of LaTeX macros involved in rendering of code-blocks
 
 Bugs fixed
 ----------

doc/latex.rst

@@ -448,6 +448,11 @@ Environments
   .. versionadded:: 1.5
      options ``verbatimwithframe``, ``verbatimwrapslines``,
      ``verbatimsep``, ``verbatimborder``.
+  .. versionadded:: 1.6.6
+     support for ``:emphasize-lines:`` option
+  .. versionadded:: 1.6.6
+     easier customizability of the formatting via exposed to user LaTeX macros
+     such as ``\sphinxVerbatimHighlightLine``.
 - the bibliography uses ``sphinxthebibliography`` and the Python Module index
   as well as the general index both use ``sphinxtheindex``; these environments
   are wrappers of the ``thebibliography`` and respectively ``theindex``

sphinx/texinputs/sphinx.sty

@@ -856,21 +856,26 @@
   \expandafter\sphinx@verbatim@checkifhl
     \expandafter{\the\numexpr\value{FancyVerbLine}-\spx@verbatim@linedelta}%
   \ifin@
-     \edef\sphinx@restorefboxsep{\fboxsep\the\fboxsep\relax}%
+     \sphinxVerbatimHighlightLine{#1}%
-     \fboxsep\z@
-     \colorbox{sphinxVerbatimHighlightColor}%
-              {\sphinx@restorefboxsep\sphinx@FancyVerbFormatLine{#1}}%
   \else
-     \sphinx@FancyVerbFormatLine{#1}%
+     \sphinxVerbatimFormatLine{#1}%
   \fi
 }%
-\def\sphinx@FancyVerbFormatLine@wrap #1%
+\newcommand\sphinxVerbatimHighlightLine[1]{%
-{\hsize\linewidth
+  \edef\sphinxrestorefboxsep{\fboxsep\the\fboxsep\relax}%
+  \fboxsep0pt\relax % cf LaTeX bug graphics/4524
+  \colorbox{sphinxVerbatimHighlightColor}%
+           {\sphinxrestorefboxsep\sphinxVerbatimFormatLine{#1}}%
+  % no need to restore \fboxsep here, as this ends up in a \hbox from fancyvrb
+}%
+% \sphinxVerbatimFormatLine will be set locally to one of those two:
+\newcommand\sphinxVerbatimFormatLineWrap[1]{%
+    \hsize\linewidth
     \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
           \doublehyphendemerits\z@\finalhyphendemerits\z@
           \strut #1\strut}%
 }%
-\def\sphinx@FancyVerbFormatLine@nowrap #1{\hb@xt@\linewidth{\strut #1\hss}}%
+\newcommand\sphinxVerbatimFormatLineNoWrap[1]{\hb@xt@\linewidth{\strut #1\hss}}%
 \def\sphinx@FancyVerbCodesHook
    {\FV@SetLineNo\edef\spx@verbatim@linedelta{\the\value{FancyVerbLine}}}%
 \g@addto@macro\FV@SetupFont{%
@@ -923,7 +928,7 @@
   %       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\sphinx@FancyVerbFormatLine\sphinx@FancyVerbFormatLine@wrap
+    \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineWrap
     \let\FV@Space\spx@verbatim@space
   % Allow breaks at special characters using \PYG... macros.
     \sphinxbreaksatspecials
@@ -931,7 +936,7 @@
     \expandafter\def\expandafter\sphinx@FancyVerbCodesHook\expandafter
                    {\sphinx@FancyVerbCodesHook\sphinxbreaksviaactive}%
   \else % end of conditional code for wrapping long code lines
-    \let\sphinx@FancyVerbFormatLine\sphinx@FancyVerbFormatLine@nowrap
+    \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineNoWrap
   \fi
   \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
   % hook into \FancyVerbCodes to recover at first code line the numbering offset