Closes #668: Allow line numbering of `code-block and literalinclude` directives

#to start at an arbitrary line number, with a new ``lineno-start`` option.

CHANGES

@@ -10,6 +10,9 @@ New features
 * #925: Allow list-typed config values to be provided on the command line,
   like ``-D key=val1,val2``.
 
+* #668: Allow line numbering of ``code-block`` and ``literalinclude`` directives
+  #to start at an arbitrary line number, with a new ``lineno-start`` option.
+
 Bugs fixed
 ----------
 

doc/markup/code.rst

@@ -86,6 +86,14 @@ on line numbers for the individual block::
 
       Some more Ruby code.
 
+The first line number can be selected with the ``lineno-start`` option.  If
+present, ``linenos`` is automatically activated as well.
+
+   .. code-block:: ruby
+      :lineno-start: 10
+
+      Some more Ruby code, with line numbering starting at 10.
+
 Additionally, an ``emphasize-lines`` option can be given to have Pygments
 emphasize particular lines::
 
@@ -101,6 +109,9 @@ emphasize particular lines::
 .. versionchanged:: 1.1
    ``emphasize-lines`` has been added.
 
+.. versionchanged:: 1.3
+   ``lineno-start`` has been added.
+
 
 Includes
 ^^^^^^^^
@@ -121,10 +132,11 @@ Includes
    Tabs in the input are expanded if you give a ``tab-width`` option with the
    desired tab width.
 
-   The directive also supports the ``linenos`` flag option to switch on line
+   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
-   numbers, the ``emphasize-lines`` option to emphasize particular lines, and
+   option to switch on line numbers, the ``lineno-start`` option to select the
-   a ``language`` option to select a language different from the current
+   first line number, the ``emphasize-lines`` option to emphasize particular
-   file's standard language.  Example with options::
+   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

sphinx/directives/code.py

@@ -56,6 +56,7 @@ class CodeBlock(Directive):
     final_argument_whitespace = False
     option_spec = {
         'linenos': directives.flag,
+        'lineno-start': int,
         'emphasize-lines': directives.unchanged_required,
     }
 
@@ -75,9 +76,13 @@ class CodeBlock(Directive):
 
         literal = nodes.literal_block(code, code)
         literal['language'] = self.arguments[0]
-        literal['linenos'] = 'linenos' in self.options
+        literal['linenos'] = 'linenos' in self.options or \
+                             'lineno-start' in self.options
+        extra_args = literal['highlight_args'] = {}
         if hl_lines is not None:
-            literal['highlight_args'] = {'hl_lines': hl_lines}
+            extra_args['hl_lines'] = hl_lines
+        if 'lineno-start' in self.options:
+            extra_args['linenostart'] = self.options['lineno-start']
         set_source_info(self, literal)
         return [literal]
 
@@ -95,6 +100,7 @@ class LiteralInclude(Directive):
     final_argument_whitespace = True
     option_spec = {
         'linenos': directives.flag,
+        'lineno-start': int,
         'tab-width': int,
         'language': directives.unchanged_required,
         'encoding': directives.encoding,
@@ -204,10 +210,13 @@ class LiteralInclude(Directive):
         set_source_info(self, retnode)
         if self.options.get('language', ''):
             retnode['language'] = self.options['language']
-        if 'linenos' in self.options:
+        retnode['linenos'] = 'linenos' in self.options or \
-            retnode['linenos'] = True
+                             'lineno-start' in self.options
+        extra_args = retnode['highlight_args'] = {}
         if hl_lines is not None:
-            retnode['highlight_args'] = {'hl_lines': hl_lines}
+            extra_args['hl_lines'] = hl_lines
+        if 'lineno-start' in self.options:
+            extra_args['linenostart'] = self.options['lineno-start']
         env.note_dependency(rel_filename)
         return [retnode]
 

tests/root/includes.txt

@@ -40,6 +40,7 @@ Literalinclude options
 .. cssclass:: inc-lines
 .. literalinclude:: literal.inc
    :lines: 6-7,9
+   :lineno-start: 6
 
 .. cssclass:: inc-startend
 .. literalinclude:: literal.inc