Added the `prepend and append` options to the

``literalinclude`` directive.

CHANGES

@@ -1,6 +1,9 @@
 Release 1.0 (in development)
 ============================
 
+* Added the ``prepend`` and ``append`` options to the
+  ``literalinclude`` directive.
+
 * Added the ``latex_docclass`` config value and made the "twoside"
   documentclass option overridable by "oneside".
 

doc/markup/code.rst

@@ -143,11 +143,17 @@ Includes
    string option, only lines that precede the first lines containing that string
    are included.
 
+   You can prepend and/or append a line to the included code, using the
+   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
+   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
+
    .. versionadded:: 0.4.3
       The ``encoding`` option.
    .. versionadded:: 0.6
       The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
       as well as support for absolute filenames.
+   .. versionadded:: 1.0
+      The ``prepend`` and ``append`` options.
 
 
 .. rubric:: Footnotes

sphinx/directives/code.py

@@ -87,6 +87,8 @@ class LiteralInclude(Directive):
         'lines': directives.unchanged_required,
         'start-after': directives.unchanged_required,
         'end-before': directives.unchanged_required,
+        'prepend': directives.unchanged_required,
+        'append': directives.unchanged_required,
     }
 
     def run(self):
@@ -144,7 +146,9 @@ class LiteralInclude(Directive):
             lines = [lines[i] for i in linelist]
 
         startafter = self.options.get('start-after')
-        endbefore = self.options.get('end-before')
+        endbefore  = self.options.get('end-before')
+        prepend    = self.options.get('prepend')
+        append     = self.options.get('append')
         if startafter is not None or endbefore is not None:
             use = not startafter
             res = []
@@ -158,6 +162,11 @@ class LiteralInclude(Directive):
                     res.append(line)
             lines = res
 
+        if prepend:
+           lines.insert(0, prepend + '\n')
+        if append:
+           lines.append(append + '\n')
+
         text = ''.join(lines)
         retnode = nodes.literal_block(text, text, source=fn)
         retnode.line = 1

tests/root/includes.txt

@@ -37,6 +37,10 @@ Literalinclude options
    :start-after: coding: utf-8
    :end-before: class Foo
 
+.. cssclass:: inc-preappend
+.. literalinclude:: literal.inc
+   :prepend: START CODE
+   :append: END CODE
 
 Testing downloadable files
 ==========================

tests/test_build.py

@@ -43,7 +43,7 @@ ENV_WARNINGS = """\
 http://www.python.org/logo.png
 %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8-sig' used for reading \
 included file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option
-%(root)s/includes.txt:56: WARNING: download file not readable: nonexisting.png
+%(root)s/includes.txt:60: WARNING: download file not readable: nonexisting.png
 """
 
 HTML_WARNINGS = ENV_WARNINGS + """\
@@ -134,6 +134,8 @@ if pygments:
             r'^class Foo:\n    pass\nclass Bar:\n$',
         ".//div[@class='inc-startend highlight-text']/div/pre":
             ur'^foo = u"Including Unicode characters: üöä"\n$',
+        ".//div[@class='inc-preappend highlight-text']/div/pre":
+            r'(?m)^START CODE$',
     })
     HTML_XPATH['subdir/includes.html'].update({
         ".//pre/span": 'line 1',