added lineno-start directive, fix for #110

Author: seanpue

doc/source/index.rst

@@ -193,7 +193,6 @@ produces:
     print('B')
     print('C')
 
-
 To add *line numbers from a specific line* to the source code, use the
 ``lineno-start`` directive::
 
@@ -216,6 +215,7 @@ produces:
 You may also emphasize particular lines in the source code with ``:emphasize-lines:``::
 
     .. jupyter-execute::
+        :lineno-start: 2
         :emphasize-lines: 2,5-6
 
         d = {
@@ -229,6 +229,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 = {

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:
@@ -54,123 +56,53 @@ def doctree(source, config=None, return_warnings=False, entrypoint="jupyter_sphi
         shutil.rmtree(tree)
 
 
-def test_basic(doctree):
+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)
-    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
-    assert cell.attributes["linenos"] is False
-    assert cell.children[0].rawsource.strip() == "2 + 2"
-    assert cell.children[1].rawsource.strip() == "4"
-
-
-def test_basic_old_entrypoint(doctree):
-    source = """
-    .. jupyter-execute::
 
-        2 + 2
     """
-    tree = doctree(source, entrypoint="jupyter_sphinx.execute")
-    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
-    assert cell.attributes["linenos"] is False
-    assert cell.children[0].rawsource.strip() == "2 + 2"
-    assert cell.children[1].rawsource.strip() == "4"
 
-
-def test_hide_output(doctree):
-    source = """
-    .. jupyter-execute::
-        :hide-output:
-
-        2 + 2
-    """
-    tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
-    assert cell.attributes["hide_output"] is True
-    assert len(cell.children) == 1
+    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"
 
-
-def test_hide_code(doctree):
-    source = """
-    .. jupyter-execute::
-        :hide-code:
-
-        2 + 2
-    """
-    tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
-    assert cell.attributes["hide_code"] is True
-    assert len(cell.children) == 1
-    assert cell.children[0].rawsource.strip() == "4"
-
-
-def test_code_below(doctree):
+    # Test continuous line numbeirng
     source = """
     .. jupyter-execute::
-        :code-below:
 
         2 + 2
-    """
-    tree = doctree(source)
-    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"
 
-
-def test_linenos(doctree):
-    source = """
     .. jupyter-execute::
-        :linenos:
 
-        2 + 2
-    """
-    tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
-    assert cell.attributes["linenos"] is True
-    assert len(cell.children) == 2
-    assert cell.children[0].rawsource.strip() == "2 + 2"
-    assert cell.children[1].rawsource.strip() == "4"
-    source = """
-    .. jupyter-execute::
-        :linenos:
-        :code-below:
+        3 + 3
 
-        2 + 2
     """
-    tree = doctree(source)
-    cell, = tree.traverse(JupyterCellNode)
-    assert len(cell.children) == 2
-    assert cell.attributes["linenos"] is True
 
+    tree = doctree(
+        source,
+        config="jupyter_sphinx_linenos = True\n"
+        "jupyter_sphinx_continue_linenos = True",
+    )
 
-def test_linenos_conf_option(doctree):
-    source = """
-    .. jupyter-execute::
-
-        2 + 2
-    """
-    tree = doctree(source, config="jupyter_sphinx_linenos = True")
-    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"
+    cell0, cell1 = tree.traverse(JupyterCellNode)
+    assert cell0.children[0].attributes["linenos"]
+    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"] == 2
+    assert cell1.children[0].rawsource.strip() == "3 + 3"
+    assert cell1.children[1].rawsource.strip() == "6"
 
-def test_continue_linenos_conf_option(doctree):
+    # Line number should continue after lineno-start option
     source = """
     .. jupyter-execute::
+       :lineno-start: 7
 
         2 + 2
 
@@ -179,16 +111,18 @@ 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].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"] == 2
+    assert cell1.children[0].attributes["highlight_args"]["linenostart"] == 8
     assert cell1.children[0].rawsource.strip() == "3 + 3"
     assert cell1.children[1].rawsource.strip() == "6"
 
@@ -272,7 +206,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 +216,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 +240,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 +252,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 +267,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 +278,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 +295,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 +313,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 +337,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 +395,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"