add emphasize-lines option to sphinx-execute directive

Author: espdev

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:
@@ -194,8 +196,10 @@ def run(self):
             hide_output=('hide-output' in self.options),
             code_below=('code-below' in self.options),
             linenos=('linenos' in self.options),
+            emphasize_lines=self.options.get('emphasize-lines'),
             raises=self.options.get('raises'),
             stderr=('stderr' in self.options),
+            _location=location,
         )]
 
 
@@ -408,12 +412,26 @@ 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
 
+                highlight_args = source['highlight_args'] = {}
+
+                if continue_linenos:
+                    highlight_args['linenostart'] = linenostart
+                    linenostart += nlines
+
+                emphasize_linespec = node['emphasize_lines']
+                if emphasize_linespec:
+                    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=node['_location'])
+                    hl_lines = [i + 1 for i in hl_lines if i < nlines]
+                    highlight_args['hl_lines'] = hl_lines
 
             # Add code cell CSS class
             for node in nodes:

tests/test_execute.py

@@ -180,6 +180,22 @@ 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
+    '''
+    tree = doctree(source)
+    cell, = tree.traverse(JupyterCellNode)
+    assert cell.attributes['emphasize_lines'] == '1,3-5'
+
+
 def test_execution_environment_carries_over(doctree):
     source = '''
     .. jupyter-execute::