add :emphasize-lines: option to source-code and literal-include

Add a new option, :emphasize-lines:, to the source-code and
literal-include directives.  The format is the same as the :lines:
option for literal-include.  The resulting list of lines is passed to
the Pygments formatter as 'hl_lines', which is only honored by the HTML
formatter.

2 files changed, 43 insertions, 2 deletions

diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index eaaf17d0..8f6d5524 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -86,6 +86,18 @@ on line numbers for the individual block::
 
       Some more Ruby code.
 
+Additionally, an ``emphasize-lines`` option can be given to have Pygments
+emphasize particular lines::
+
+    .. code-block:: python
+       :emphasize-lines: 3,5
+
+       def some_function():
+           interesting = False
+           print 'This line is highlighted.'
+           print 'This one is not...'
+           print '...but this one is.'
+
 
 Includes
 ^^^^^^^^
@@ -107,11 +119,13 @@ Includes
    desired tab width.
 
    The directive also supports the ``linenos`` flag option to switch on line
-   numbers, and a ``language`` option to select a language different from the
-   current file's standard language.  Example with options::
+   numbers, the ``emphasize-lines`` option to emphasize particular lines, and
+   a ``language`` option to select a language different from the current
+   file's standard language.  Example with options::
 
       .. literalinclude:: example.rb
          :language: ruby
+         :emphasize-lines: 12,15-18
          :linenos:
 
    Include files are assumed to be encoded in the :confval:`source_encoding`.
diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py
index 8cedab19..f41ca3a6 100644
--- a/sphinx/directives/code.py
+++ b/sphinx/directives/code.py
@@ -55,13 +55,28 @@ class CodeBlock(Directive):
     final_argument_whitespace = False
     option_spec = {
         'linenos': directives.flag,
+        'emphasize-lines': directives.unchanged_required,
     }
 
     def run(self):
         code = u'\n'.join(self.content)
+
+        linespec = self.options.get('emphasize-lines')
+        if linespec:
+            try:
+                nlines = len(self.content)
+                hl_lines = [x+1 for x in parselinenos(linespec, nlines)]
+            except ValueError, err:
+                document = self.state.document
+                return [document.reporter.warning(str(err), line=self.lineno)]
+        else:
+            hl_lines = None
+
         literal = nodes.literal_block(code, code)
         literal['language'] = self.arguments[0]
         literal['linenos'] = 'linenos' in self.options
+        if hl_lines is not None:
+            literal['highlight_args'] = {'hl_lines': hl_lines}
         literal.line = self.lineno
         return [literal]
 
@@ -88,6 +103,7 @@ class LiteralInclude(Directive):
         'end-before': directives.unchanged_required,
         'prepend': directives.unchanged_required,
         'append': directives.unchanged_required,
+        'emphasize-lines': directives.unchanged_required,
     }
 
     def run(self):
@@ -146,6 +162,15 @@ class LiteralInclude(Directive):
                     'Line spec %r: no lines pulled from include file %r' %
                     (linespec, filename), line=self.lineno)]
 
+        linespec = self.options.get('emphasize-lines')
+        if linespec:
+            try:
+                hl_lines = [x+1 for x in parselinenos(linespec, len(lines))]
+            except ValueError, err:
+                return [document.reporter.warning(str(err), line=self.lineno)]
+        else:
+            hl_lines = None
+
         startafter = self.options.get('start-after')
         endbefore  = self.options.get('end-before')
         prepend    = self.options.get('prepend')
@@ -178,6 +203,8 @@ class LiteralInclude(Directive):
             retnode['language'] = self.options['language']
         if 'linenos' in self.options:
             retnode['linenos'] = True
+        if hl_lines is not None:
+            retnode['highlight_args'] = {'hl_lines': hl_lines}
         env.note_dependency(rel_filename)
         return [retnode]