From 2458e5731afbc1eda73548b8b0945fa38c73f517 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sun, 19 Jan 2014 11:04:12 +0100
Subject: [PATCH] Add :filename: also for literalinclude. Changelog entry.

---
 CHANGES                   |  4 ++++
 doc/markup/code.rst       | 19 +++++++++++++++++++
 sphinx/directives/code.py |  6 ++++++
 3 files changed, 29 insertions(+)

diff --git a/CHANGES b/CHANGES
index f3f3b1c12..42d544b02 100644
--- a/CHANGES
+++ b/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
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 6e707e007..e9f8f1da4 100644
--- a/doc/markup/code.rst
+++ b/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
diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py
index bfe6c48e9..6900ea6b6 100644
--- a/sphinx/directives/code.py
+++ b/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