Merge pull request #113 from seanpue/master

Fix for #110 and added :lineno-start: directive

Author: akhmerov

doc/source/index.rst

@@ -177,12 +177,12 @@ produces:
 
 You may also add *line numbers* to the source code with ``:linenos:``::
 
-    .. jupyter-execute::
-        :linenos:
+  .. jupyter-execute::
+     :linenos:
 
-        print('A')
-        print('B')
-        print('C')
+     print('A')
+     print('B')
+     print('C')
 
 produces:
 
@@ -193,6 +193,25 @@ produces:
     print('B')
     print('C')
 
+To add *line numbers from a specific line* to the source code, use the
+``lineno-start`` directive::
+
+  .. jupyter-execute::
+     :lineno-start: 7
+
+     print('A')
+     print('B')
+     print('C')
+
+produces:
+
+.. jupyter-execute::
+    :lineno-start: 7
+
+    print('A')
+    print('B')
+    print('C')
+
 You may also emphasize particular lines in the source code with ``:emphasize-lines:``::
 
     .. jupyter-execute::
@@ -209,6 +228,7 @@ You may also emphasize particular lines in the source code with ``:emphasize-lin
 produces:
 
 .. jupyter-execute::
+    :lineno-start: 2
     :emphasize-lines: 2,5-6
 
     d = {
@@ -379,4 +399,5 @@ jupyter_sphinx_linenos
 
 jupyter_sphinx_continue_linenos
 
-    Whether to show continuous line numbering in all ``jupyter-execute`` sources.
+    Whether to continue line numbering from previous cell in all ``jupyter-execute``
+    sources.

jupyter_sphinx/ast.py

@@ -45,6 +45,9 @@ 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.
+    lineno-start: nonnegative int
+        If provided, the code will be show with line numbering beginning from
+        specified line.
     emphasize-lines : comma separated list of line numbers
         If provided, the specified lines will be highlighted.
     raises : comma separated list of exception types
@@ -70,6 +73,7 @@ class JupyterCell(Directive):
         "hide-output": directives.flag,
         "code-below": directives.flag,
         "linenos": directives.flag,
+        "lineno-start": directives.nonnegative_int,
         "emphasize-lines": directives.unchanged_required,
         "raises": csv_option,
         "stderr": directives.flag,
@@ -78,6 +82,7 @@ class JupyterCell(Directive):
     def run(self):
         # This only works lazily because the logger is inited by Sphinx
         from . import logger
+
         location = self.state_machine.get_source_and_line(self.lineno)
 
         if self.arguments:
@@ -103,6 +108,7 @@ def run(self):
 
         # 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:
@@ -129,6 +135,7 @@ def run(self):
                 hide_output=("hide-output" in self.options),
                 code_below=("code-below" in self.options),
                 linenos=("linenos" in self.options),
+                linenostart=(self.options.get("lineno-start")),
                 emphasize_lines=hl_lines,
                 raises=self.options.get("raises"),
                 stderr=("stderr" in self.options),

jupyter_sphinx/execute.py

@@ -171,20 +171,25 @@ def apply(self):
                 source = node.children[0]
                 source.attributes["language"] = lexer
 
-            # Add line numbers to code cells if jupyter_sphinx_linenos or
-            # jupyter_sphinx_continue_linenos are set in the configuration,
-            # or the linenos directive is set.
-            # Update current line numbers from cell if jupyter_sphinx_continue_linenos
-            # is set.
+            # Add line numbering
+
             linenostart = 1
+
             for node in nodes:
                 source = node.children[0]
                 nlines = source.rawsource.count("\n") + 1
+                show_numbering = (
+                    linenos_config or node["linenos"] or node["linenostart"]
+                )
 
-                if linenos_config or continue_linenos or node["linenos"]:
+                if show_numbering:
                     source["linenos"] = True
-                if continue_linenos:
-                    source["highlight_args"] = {"linenostart": linenostart}
+                    if node["linenostart"]:
+                        linenostart = node["linenostart"]
+                    if node["linenostart"] or continue_linenos:
+                        source["highlight_args"] = {"linenostart": linenostart}
+                    else:
+                        linenostart = 1
                     linenostart += nlines
 
                 hl_lines = node["emphasize_lines"]
@@ -275,6 +280,7 @@ def setup(app):
     """
     # To avoid circular imports we'll lazily import
     from . import setup as jssetup
+
     js.logger.warning(
         (
             "`jupyter-sphinx` was initialized with the "

tests/test_execute.py

@@ -24,7 +24,9 @@ def doctree():
     apps = []
     syspath = sys.path[:]
 
-    def doctree(source, config=None, return_warnings=False, entrypoint="jupyter_sphinx"):
+    def doctree(
+        source, config=None, return_warnings=False, entrypoint="jupyter_sphinx"
+    ):
         src_dir = tempfile.mkdtemp()
         source_trees.append(src_dir)
         with open(os.path.join(src_dir, "conf.py"), "w") as f:
@@ -61,7 +63,7 @@ def test_basic(doctree):
         2 + 2
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["code_below"] is False
     assert cell.attributes["hide_code"] is False
     assert cell.attributes["hide_output"] is False
@@ -77,7 +79,7 @@ def test_basic_old_entrypoint(doctree):
         2 + 2
     """
     tree = doctree(source, entrypoint="jupyter_sphinx.execute")
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["code_below"] is False
     assert cell.attributes["hide_code"] is False
     assert cell.attributes["hide_output"] is False
@@ -94,7 +96,7 @@ def test_hide_output(doctree):
         2 + 2
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["hide_output"] is True
     assert len(cell.children) == 1
     assert cell.children[0].rawsource.strip() == "2 + 2"
@@ -108,7 +110,7 @@ def test_hide_code(doctree):
         2 + 2
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["hide_code"] is True
     assert len(cell.children) == 1
     assert cell.children[0].rawsource.strip() == "4"
@@ -122,7 +124,7 @@ def test_code_below(doctree):
         2 + 2
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["code_below"] is True
     assert cell.children[0].rawsource.strip() == "4"
     assert cell.children[1].rawsource.strip() == "2 + 2"
@@ -136,7 +138,7 @@ def test_linenos(doctree):
         2 + 2
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["linenos"] is True
     assert len(cell.children) == 2
     assert cell.children[0].rawsource.strip() == "2 + 2"
@@ -149,7 +151,7 @@ def test_linenos(doctree):
         2 + 2
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert len(cell.children) == 2
     assert cell.attributes["linenos"] is True
 
@@ -161,14 +163,29 @@ def test_linenos_conf_option(doctree):
         2 + 2
     """
     tree = doctree(source, config="jupyter_sphinx_linenos = True")
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.children[0].attributes["linenos"]
     assert "highlight_args" not in cell.children[0].attributes
     assert cell.children[0].rawsource.strip() == "2 + 2"
     assert cell.children[1].rawsource.strip() == "4"
 
 
 def test_continue_linenos_conf_option(doctree):
+    # Test no linenumbering without linenos config or lineno-start directive
+    source = """
+    .. jupyter-execute::
+
+        2 + 2
+
+    """
+
+    tree = doctree(source, config="jupyter_sphinx_continue_linenos = True")
+    (cell,) = tree.traverse(JupyterCellNode)
+    assert "linenos" not in cell.children[0].attributes
+    assert cell.children[0].rawsource.strip() == "2 + 2"
+    assert cell.children[1].rawsource.strip() == "4"
+
+    # Test continuous line numbering
     source = """
     .. jupyter-execute::
 
@@ -179,11 +196,15 @@ def test_continue_linenos_conf_option(doctree):
         3 + 3
 
     """
-    continue_linenos_config = "jupyter_sphinx_continue_linenos = True"
-    tree = doctree(source, config=continue_linenos_config)
+
+    tree = doctree(
+        source,
+        config="jupyter_sphinx_linenos = True\n"
+        "jupyter_sphinx_continue_linenos = True",
+    )
+
     cell0, cell1 = tree.traverse(JupyterCellNode)
     assert cell0.children[0].attributes["linenos"]
-    assert cell0.children[0].attributes["highlight_args"]["linenostart"] == 1
     assert cell0.children[0].rawsource.strip() == "2 + 2"
     assert cell0.children[1].rawsource.strip() == "4"
 
@@ -192,6 +213,34 @@ def test_continue_linenos_conf_option(doctree):
     assert cell1.children[0].rawsource.strip() == "3 + 3"
     assert cell1.children[1].rawsource.strip() == "6"
 
+    # Line number should continue after lineno-start option
+
+    source = """
+    .. jupyter-execute::
+       :lineno-start: 7
+
+        2 + 2
+
+    .. jupyter-execute::
+
+        3 + 3
+
+    """
+    tree = doctree(
+        source,
+        config="jupyter_sphinx_linenos = True\n"
+        "jupyter_sphinx_continue_linenos = True",
+    )
+    cell0, cell1 = tree.traverse(JupyterCellNode)
+    assert cell0.children[0].attributes["highlight_args"]["linenostart"] == 7
+    assert cell0.children[0].rawsource.strip() == "2 + 2"
+    assert cell0.children[1].rawsource.strip() == "4"
+
+    assert cell1.children[0].attributes["linenos"]
+    assert cell1.children[0].attributes["highlight_args"]["linenostart"] == 8
+    assert cell1.children[0].rawsource.strip() == "3 + 3"
+    assert cell1.children[1].rawsource.strip() == "6"
+
 
 def test_emphasize_lines(doctree):
     source = """
@@ -272,7 +321,7 @@ def test_raises(doctree):
         raise ValueError()
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert "ValueError" in cell.children[1].rawsource
 
     source = """
@@ -282,7 +331,7 @@ def test_raises(doctree):
         raise ValueError()
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert "ValueError" in cell.children[1].rawsource
 
 
@@ -306,8 +355,8 @@ def test_javascript(doctree):
         Javascript('window.alert("Hello world!")')
     """
     tree = doctree(source)
-    node, = list(tree.traverse(raw))
-    text, = node.children
+    (node,) = list(tree.traverse(raw))
+    (text,) = node.children
     assert "world" in text
 
 
@@ -318,7 +367,7 @@ def test_stdout(doctree):
         print('hello world')
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert len(cell.children) == 2
     assert cell.children[1].rawsource.strip() == "hello world"
 
@@ -333,7 +382,7 @@ def test_stderr(doctree):
 
     tree, warnings = doctree(source, return_warnings=True)
     assert "hello world" in warnings
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert len(cell.children) == 1  # no output
 
     source = """
@@ -344,7 +393,7 @@ def test_stderr(doctree):
         print('hello world', file=sys.stderr)
     """
     tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert len(cell.children) == 2
     assert "stderr" in cell.children[1].attributes["classes"]
     assert cell.children[1].astext().strip() == "hello world"
@@ -361,7 +410,7 @@ def test_thebe_hide_output(doctree):
         2 + 2
     """
     tree = doctree(source, thebe_config)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["hide_output"] is True
     assert len(cell.children) == 1
 
@@ -379,7 +428,7 @@ def test_thebe_hide_code(doctree):
         2 + 2
     """
     tree = doctree(source, thebe_config)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["hide_code"] is True
     assert len(cell.children) == 2
 
@@ -403,7 +452,7 @@ def test_thebe_code_below(doctree):
         2 + 2
     """
     tree = doctree(source, thebe_config)
-    cell, = tree.traverse(JupyterCellNode)
+    (cell,) = tree.traverse(JupyterCellNode)
     assert cell.attributes["code_below"] is True
 
     output = cell.children[0]
@@ -461,5 +510,5 @@ def test_latex(doctree):
 
     for start, end in delimiter_pairs:
         tree = doctree(source.format(start, end))
-        cell, = tree.traverse(JupyterCellNode)
+        (cell,) = tree.traverse(JupyterCellNode)
         assert cell.children[1].astext() == r"\int"