Add :filename: also for literalinclude. Changelog entry.

CHANGES

@@ -27,6 +27,10 @@ New features
 * #668: Allow line numbering of ``code-block`` and ``literalinclude`` directives
   to start at an arbitrary line number, with a new ``lineno-start`` option.
 
+* PR#172: The :rst:dir:`code-block` and :rst:dir:`literalinclude` directives now
+  can have a ``filename`` option that shows a filename before the code in the
+  output.
+
 * Prompt for the document language in sphinx-quickstart.
 
 Bugs fixed

doc/markup/code.rst

@@ -188,6 +188,25 @@ Includes
       The ``prepend`` and ``append`` options, as well as ``tab-width``.
 
 
+Showing a file name
+^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.3
+
+A ``filename`` option can be given to show that name before the code block.  For
+example::
+
+   .. code-block:: python
+      :filename: this.py
+
+      print 'Explicit is better than implicit.'
+
+
+:rst:dir:`literalinclude` also supports the ``filename`` option, with the
+additional feature that if you leave the value empty, the shown filename will be
+exactly the one given as an argument.
+
+
 .. rubric:: Footnotes
 
 .. [1] There is a standard ``.. include`` directive, but it raises errors if the

sphinx/directives/code.py

@@ -115,6 +115,7 @@ class LiteralInclude(Directive):
         'prepend': directives.unchanged_required,
         'append': directives.unchanged_required,
         'emphasize-lines': directives.unchanged_required,
+        'filename': directives.unchanged,
     }
 
     def run(self):
@@ -216,6 +217,11 @@ class LiteralInclude(Directive):
             retnode['language'] = self.options['language']
         retnode['linenos'] = 'linenos' in self.options or \
                              'lineno-start' in self.options
+        filename = self.options.get('filename')
+        if filename is not None:
+            if not filename:
+                filename = self.arguments[0]
+            retnode['filename'] = filename
         extra_args = retnode['highlight_args'] = {}
         if hl_lines is not None:
             extra_args['hl_lines'] = hl_lines