Added `tab-width option to literalinclude` directive.

CHANGES

@@ -1,6 +1,8 @@
 Release 1.0 (in development)
 ============================
 
+* Added ``tab-width`` option to ``literalinclude`` directive.
+
 * The ``html_sidebars`` config value can now contain patterns as
   keys, and the values can be lists that explicitly select which
   sidebar templates should be rendered.  That means that the builtin

doc/markup/code.rst

@@ -103,6 +103,9 @@ Includes
    is absolute (starting with ``/``), it is relative to the top source
    directory.
 
+   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, and a ``language`` option to select a language different from the
    current file's standard language.  Example with options::
@@ -153,7 +156,7 @@ Includes
       The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
       as well as support for absolute filenames.
    .. versionadded:: 1.0
-      The ``prepend`` and ``append`` options.
+      The ``prepend`` and ``append`` options, as well as ``tab-width``.
 
 
 .. rubric:: Footnotes

sphinx/directives/code.py

@@ -81,6 +81,7 @@ class LiteralInclude(Directive):
     final_argument_whitespace = False
     option_spec = {
         'linenos': directives.flag,
+        'tab-width': int,
         'language': directives.unchanged_required,
         'encoding': directives.encoding,
         'pyobject': directives.unchanged_required,
@@ -174,6 +175,8 @@ class LiteralInclude(Directive):
            lines.append(append + '\n')
 
         text = ''.join(lines)
+        if self.options.get('tab-width'):
+            text = text.expandtabs(self.options['tab-width'])
         retnode = nodes.literal_block(text, text, source=fn)
         retnode.line = 1
         if self.options.get('language', ''):

tests/root/includes.txt

@@ -49,6 +49,16 @@ Literalinclude options
    :prepend: START CODE
    :append: END CODE
 
+.. cssclass:: inc-tab3
+.. literalinclude:: tabs.inc
+   :tab-width: 3
+   :language: text
+
+.. cssclass:: inc-tab8
+.. literalinclude:: tabs.inc
+   :tab-width: 8
+   :language: python
+
 Test if dedenting before parsing works.
 
 .. highlight:: python

tests/root/tabs.inc

@@ -0,0 +1,5 @@
+Tabs include file test
+----------------------
+
+The next line has a tab:
+-|	|-

tests/test_build_html.py

@@ -119,18 +119,22 @@ HTML_XPATH = {
 if pygments:
     HTML_XPATH['includes.html'].update({
         ".//pre/span[@class='s']": u'üöä',
-        ".//div[@class='inc-pyobj1 highlight-text']/div/pre":
+        ".//div[@class='inc-pyobj1 highlight-text']//pre":
             r'^class Foo:\n    pass\n\s*$',
-        ".//div[@class='inc-pyobj2 highlight-text']/div/pre":
+        ".//div[@class='inc-pyobj2 highlight-text']//pre":
             r'^    def baz\(\):\n        pass\n\s*$',
-        ".//div[@class='inc-lines highlight-text']/div/pre":
+        ".//div[@class='inc-lines highlight-text']//pre":
             r'^class Foo:\n    pass\nclass Bar:\n$',
-        ".//div[@class='inc-startend highlight-text']/div/pre":
+        ".//div[@class='inc-startend highlight-text']//pre":
             ur'^foo = u"Including Unicode characters: üöä"\n$',
-        ".//div[@class='inc-preappend highlight-text']/div/pre":
+        ".//div[@class='inc-preappend highlight-text']//pre":
             r'(?m)^START CODE$',
-        ".//div[@class='inc-pyobj-dedent highlight-python']/div/pre/span":
+        ".//div[@class='inc-pyobj-dedent highlight-python']//span":
             r'def',
+        ".//div[@class='inc-tab3 highlight-text']//pre":
+            r'-| |-',
+        ".//div[@class='inc-tab8 highlight-python']//pre":
+            r'-|      |-',
     })
     HTML_XPATH['subdir/includes.html'].update({
         ".//pre/span": 'line 1',