diff --git a/CHANGES b/CHANGES index 58311eb4b..5ddb5cffe 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/markup/code.rst b/doc/markup/code.rst index c0e7e8ebe..7b958bc9d 100644 --- a/doc/markup/code.rst +++ b/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 - numbers, the ``emphasize-lines`` option to emphasize particular lines, and - a ``language`` option to select a language different from the current - file's standard language. Example with options:: + Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag + option to switch on line numbers, the ``lineno-start`` option to select the + first line number, the ``emphasize-lines`` option to emphasize particular + 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 diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 4d43e5ff6..7b1acfd58 100644 --- a/sphinx/directives/code.py +++ b/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'] = True + retnode['linenos'] = 'linenos' in self.options or \ + '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] diff --git a/tests/root/includes.txt b/tests/root/includes.txt index 904f06773..089178119 100644 --- a/tests/root/includes.txt +++ b/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