Commits

Mark Lodato committed 326d3db

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.

Comments (0)

Files changed (2)

doc/markup/code.rst

 
       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
 ^^^^^^^^
    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`.

sphinx/directives/code.py

     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]
 
         'end-before': directives.unchanged_required,
         'prepend': directives.unchanged_required,
         'append': directives.unchanged_required,
+        'emphasize-lines': directives.unchanged_required,
     }
 
     def run(self):
                     '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')
             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]
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.