Merge pull request #95 from espdev/emphasize-lines

Add emphasize-lines option

Author: akhmerov

doc/source/index.rst

@@ -193,6 +193,32 @@ produces:
     print('B')
     print('C')
 
+You may also emphasize particular lines in the source code with ``:emphasize-lines:``::
+
+    .. jupyter-execute::
+        :emphasize-lines: 2,5-6
+
+        d = {
+            'a': 1,
+            'b': 2,
+            'c': 3,
+            'd': 4,
+            'e': 5,
+        }
+
+produces:
+
+.. jupyter-execute::
+    :emphasize-lines: 2,5-6
+
+    d = {
+        'a': 1,
+        'b': 2,
+        'c': 3,
+        'd': 4,
+        'e': 5,
+    }
+
 Controlling exceptions
 ----------------------
 

jupyter_sphinx/execute.py

@@ -2,11 +2,9 @@
 
 import os
 from itertools import groupby, count
-from operator import itemgetter
 import json
 
-import sphinx
-from sphinx.util import logging
+from sphinx.util import logging, parselinenos
 from sphinx.util.fileutil import copy_asset
 from sphinx.transforms import SphinxTransform
 from sphinx.errors import ExtensionError
@@ -26,7 +24,6 @@
 
 import nbformat
 
-from ipywidgets import Widget
 import ipywidgets.embed
 
 from ._version import __version__
@@ -136,6 +133,8 @@ class JupyterCell(Directive):
         If provided, the code will be shown below the cell output.
     linenos : bool
         If provided, the code will be shown with line numbering.
+    emphasize-lines : comma separated list of line numbers
+        If provided, the specified lines will be highlighted.
     raises : comma separated list of exception types
         If provided, a comma-separated list of exception type names that
         the cell may raise. If one of the listed execption types is raised
@@ -159,11 +158,14 @@ class JupyterCell(Directive):
         'hide-output': directives.flag,
         'code-below': directives.flag,
         'linenos': directives.flag,
+        'emphasize-lines': directives.unchanged_required,
         'raises': csv_option,
         'stderr': directives.flag,
     }
 
     def run(self):
+        location = self.state_machine.get_source_and_line(self.lineno)
+
         if self.arguments:
             # As per 'sphinx.directives.code.LiteralInclude'
             env = self.state.document.settings.env
@@ -172,7 +174,7 @@ def run(self):
             if self.content:
                 logger.warning(
                     'Ignoring inline code in Jupyter cell included from "{}"'
-                    .format(rel_filename)
+                    .format(rel_filename), location=location
                 )
             try:
                 with open(filename) as f:
@@ -185,6 +187,23 @@ def run(self):
             self.assert_has_content()
             content = self.content
 
+        # The code fragment is taken from CodeBlock directive almost unchanged:
+        # https://github.com/sphinx-doc/sphinx/blob/0319faf8f1503453b6ce19020819a8cf44e39f13/sphinx/directives/code.py#L134-L148
+        emphasize_linespec = self.options.get('emphasize-lines')
+        if emphasize_linespec:
+            try:
+                nlines = len(content)
+                hl_lines = parselinenos(emphasize_linespec, nlines)
+                if any(i >= nlines for i in hl_lines):
+                    logger.warning(
+                        'Line number spec is out of range(1-{}): {}'.format(
+                            nlines, emphasize_linespec), location=location)
+                hl_lines = [i + 1 for i in hl_lines if i < nlines]
+            except ValueError as err:
+                return [self.state.document.reporter.warning(err, line=self.lineno)]
+        else:
+            hl_lines = []
+
         return [JupyterCellNode(
             '',
             docutils.nodes.literal_block(
@@ -194,6 +213,7 @@ def run(self):
             hide_output=('hide-output' in self.options),
             code_below=('code-below' in self.options),
             linenos=('linenos' in self.options),
+            emphasize_lines=hl_lines,
             raises=self.options.get('raises'),
             stderr=('stderr' in self.options),
         )]
@@ -408,12 +428,18 @@ def apply(self):
             linenostart = 1
             for node in nodes:
                 source = node.children[0]
+                nlines = source.rawsource.count("\n") + 1
+
                 if linenos_config or continue_linenos or node["linenos"]:
                     source["linenos"] = True
                 if continue_linenos:
-                    source["highlight_args"] = {'linenostart': linenostart}
-                    linenostart += source.rawsource.count("\n") + 1
+                    source['highlight_args'] = {'linenostart': linenostart}
+                    linenostart += nlines
 
+                hl_lines = node['emphasize_lines']
+                if hl_lines:
+                    highlight_args = source.setdefault('highlight_args', {})
+                    highlight_args['hl_lines'] = hl_lines
 
             # Add code cell CSS class
             for node in nodes:

tests/test_execute.py

@@ -180,6 +180,33 @@ def test_continue_linenos_conf_option(doctree):
     assert cell1.children[1].rawsource.strip() == "6"
 
 
+def test_emphasize_lines(doctree):
+    source = '''
+    .. jupyter-execute::
+        :emphasize-lines: 1,3-5
+
+        1 + 1
+        2 + 2
+        3 + 3
+        4 + 4
+        5 + 5
+    
+    .. jupyter-execute::
+        :emphasize-lines: 2, 4
+
+        1 + 1
+        2 + 2
+        3 + 3
+        4 + 4
+        5 + 5
+    '''
+    tree = doctree(source)
+    cell0, cell1 = tree.traverse(JupyterCellNode)
+
+    assert cell0.attributes['emphasize_lines'] == [1, 3, 4, 5]
+    assert cell1.attributes['emphasize_lines'] == [2, 4]
+
+
 def test_execution_environment_carries_over(doctree):
     source = '''
     .. jupyter-execute::