Merge pull request #4285 from jfbu/1238_PDF_emphasize-lines

Support ``:emphasize-lines:`` in PDF output (closes #1238)

doc/latex.rst

@@ -256,6 +256,11 @@ The available styling options
 ``VerbatimBorderColor``
     default ``{rgb}{0,0,0}``. The frame color, defaults to black.
 
+``VerbatimHighlightColor``
+    default ``{rgb}{0.878,1,1}``. The color for highlighted lines.
+
+    .. versionadded:: 1.6.6
+
 ``verbatimsep``
     default ``\fboxsep``. The separation between code lines and the frame.
 

doc/markup/code.rst

@@ -121,6 +121,8 @@ emphasize particular lines::
 .. versionchanged:: 1.3
    ``lineno-start`` has been added.
 
+.. versionchanged:: 1.6.6
+   LaTeX supports the ``emphasize-lines`` option.
 
 Includes
 ^^^^^^^^
@@ -188,8 +190,8 @@ Includes
    ``lines``, the first allowed line having by convention the line number ``1``.
 
    When lines have been selected in any of the ways described above, the
-   line numbers in ``emphasize-lines`` also refer to the selection, with the
-   first selected line having number ``1``.
+   line numbers in ``emphasize-lines`` refer to those selected lines, counted
+   consecutively starting at ``1``.
 
    When specifying particular parts of a file to display, it can be useful to
    display the original line numbers. This can be done using the

sphinx/texinputs/sphinx.sty

@@ -159,6 +159,7 @@
 % For highlighted code.
 \RequirePackage{fancyvrb}
 \fvset{fontsize=\small}
+\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
 % For hyperlinked footnotes in tables; also for gathering footnotes from
 % topic and warning blocks. Also to allow code-blocks in footnotes.
 \RequirePackage{footnotehyper-sphinx}
@@ -310,6 +311,8 @@
 \sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}}
 \sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}}
 \sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}}
+% also no prefix for this one, for consistency (sigh). Color as in minted!
+\sphinxDeclareColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}}
 % now the colours defined with "sphinx" prefix in their names
 \newcommand*{\sphinxDeclareSphinxColorOption}[2]{%
    % set the initial default
@@ -848,6 +851,32 @@
 
 % needed to create wrapper environments of fancyvrb's Verbatim
 \newcommand*{\sphinxVerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}}
+% serves to implement line highlighting and line wrapping
+\newcommand\sphinxFancyVerbFormatLine[1]{%
+  \expandafter\sphinx@verbatim@checkifhl
+    \expandafter{\the\numexpr\value{FancyVerbLine}-\spx@verbatim@linedelta}%
+  \ifin@
+     \edef\sphinx@restorefboxsep{\fboxsep\the\fboxsep\relax}%
+     \fboxsep\z@
+     \colorbox{VerbatimHighlightColor}%
+              {\sphinx@restorefboxsep\sphinx@FancyVerbFormatLine{#1}}%
+  \else
+     \sphinx@FancyVerbFormatLine{#1}%
+  \fi
+}%
+\def\sphinx@FancyVerbFormatLine@wrap #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}}%
+\def\sphinx@FancyVerbCodesHook
+   {\FV@SetLineNo\edef\spx@verbatim@linedelta{\the\value{FancyVerbLine}}}%
+\g@addto@macro\FV@SetupFont{%
+    \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
+    \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
+}%
 % Sphinx <1.5 optional argument was in fact mandatory. It is now really
 % optional and handled by original Verbatim.
 \newenvironment{sphinxVerbatim}{%
@@ -894,20 +923,20 @@
   %       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).
-  \expandafter\def\expandafter\FV@SetupFont\expandafter
-    {\FV@SetupFont\sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
-                  \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}}%
-  \def\FancyVerbFormatLine ##1{\hsize\linewidth
-          \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
-                \doublehyphendemerits\z@\finalhyphendemerits\z@
-                \strut ##1\strut}%
-          }%
-  \let\FV@Space\spx@verbatim@space
+    \let\sphinx@FancyVerbFormatLine\sphinx@FancyVerbFormatLine@wrap
+    \let\FV@Space\spx@verbatim@space
   % Allow breaks at special characters using \PYG... macros.
-  \sphinxbreaksatspecials
+    \sphinxbreaksatspecials
   % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
-  \def\FancyVerbCodes{\sphinxbreaksviaactive}%
-  \fi % end of conditional code for wrapping long code lines
+    \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
+  \fi
+  \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
+  % hook into \FancyVerbCodes to recover at first code line the numbering offset
+  \expandafter\def\expandafter\FancyVerbCodes\expandafter
+      {\FancyVerbCodes\sphinx@FancyVerbCodesHook}%
   % go around fancyvrb's check of \@currenvir
   \let\VerbatimEnvironment\sphinxVerbatimEnvironment
   % go around fancyvrb's check of current list depth

sphinx/writers/latex.py

@@ -2270,6 +2270,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
             lang = self.hlsettingstack[-1][0]
             linenos = code.count('\n') >= self.hlsettingstack[-1][1] - 1
             highlight_args = node.get('highlight_args', {})
+            hllines = '\\fvset{hllines={, %s,}}%%' %\
+                      str(highlight_args.get('hl_lines', []))[1:-1]
             if 'language' in node:
                 # code-block directives
                 lang = node['language']
@@ -2308,7 +2310,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 hlcode += '\\end{sphinxVerbatimintable}'
             else:
                 hlcode += '\\end{sphinxVerbatim}'
-            self.body.append('\n' + hlcode + '\n')
+            self.body.append('\n' + hllines + '\n' + hlcode + '\n')
             if ids:
                 self.body.append('\\let\\sphinxLiteralBlockLabel\\empty\n')
             raise nodes.SkipNode

tests/roots/test-directive-code/emphasize.rst

@@ -0,0 +1,7 @@
+Literal Includes with Highlighted Lines
+=======================================
+
+.. literalinclude:: target.py
+   :language: python
+   :emphasize-lines: 5-6, 13-15, 24-
+

tests/roots/test-latex-table/expects/longtable_having_verbatim.tex

@@ -27,6 +27,7 @@ header2
 
 \endlastfoot
 
+\fvset{hllines={, ,}}%
 \begin{sphinxVerbatimintable}[commandchars=\\\{\}]
 \PYG{n}{hello} \PYG{n}{world}
 \end{sphinxVerbatimintable}

tests/roots/test-latex-table/expects/table_having_verbatim.tex

@@ -10,6 +10,7 @@ header1
 header2
 \unskip}\relax \\
 \hline
+\fvset{hllines={, ,}}%
 \begin{sphinxVerbatimintable}[commandchars=\\\{\}]
 \PYG{n}{hello} \PYG{n}{world}
 \end{sphinxVerbatimintable}

tests/test_directive_code.py

@@ -349,6 +349,14 @@ def test_code_block_namedlink_latex(app, status, warning):
     assert link2 in latex
 
 
+@pytest.mark.sphinx('latex', testroot='directive-code')
+def test_code_block_emphasize_latex(app, status, warning):
+    app.builder.build(['emphasize'])
+    latex = (app.outdir / 'Python.tex').text(encoding='utf-8').replace('\r\n', '\n')
+    includes = '\\fvset{hllines={, 5, 6, 13, 14, 15, 24, 25, 26, 27,}}%\n'
+    assert includes in latex
+
+
 @pytest.mark.sphinx('xml', testroot='directive-code')
 def test_literal_include(app, status, warning):
     app.builder.build(['index'])

tests/test_markup.py

@@ -211,7 +211,8 @@ def get_verifier(verify, verify_re):
         'verify',
         u'::\n\n @Γ\\∞${}',
         None,
-        (u'\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n'
+        (u'\\fvset{hllines={, ,}}%\n'
+         u'\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n'
          u'@\\(\\Gamma\\)\\PYGZbs{}\\(\\infty\\)\\PYGZdl{}\\PYGZob{}\\PYGZcb{}\n'
          u'\\end{sphinxVerbatim}'),
     ),