Rename :filename: option of code-block directive to :caption:

13 files changed, 90 insertions, 26 deletions

diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py
index 7f08b814..c0b27dff 100644
--- a/sphinx/directives/code.py
+++ b/sphinx/directives/code.py
@@ -74,7 +74,7 @@ class CodeBlock(Directive):
         'dedent': int,
         'lineno-start': int,
         'emphasize-lines': directives.unchanged_required,
-        'filename': directives.unchanged_required,
+        'caption': directives.unchanged_required,
     }
 
     def run(self):
@@ -98,9 +98,9 @@ class CodeBlock(Directive):
 
         literal = nodes.literal_block(code, code)
         literal['language'] = self.arguments[0]
-        filename = self.options.get('filename')
-        if filename:
-            literal['filename'] = filename
+        caption = self.options.get('caption')
+        if caption:
+            literal['caption'] = caption
         literal['linenos'] = 'linenos' in self.options or \
                              'lineno-start' in self.options
         extra_args = literal['highlight_args'] = {}
@@ -137,7 +137,7 @@ class LiteralInclude(Directive):
         'prepend': directives.unchanged_required,
         'append': directives.unchanged_required,
         'emphasize-lines': directives.unchanged_required,
-        'filename': directives.unchanged,
+        'caption': directives.unchanged,
     }
 
     def run(self):
@@ -240,11 +240,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
+        caption = self.options.get('caption')
+        if caption is not None:
+            if not caption:
+                caption = self.arguments[0]
+            retnode['caption'] = caption
         extra_args = retnode['highlight_args'] = {}
         if hl_lines is not None:
             extra_args['hl_lines'] = hl_lines
diff --git a/sphinx/themes/agogo/static/agogo.css_t b/sphinx/themes/agogo/static/agogo.css_t
index 9cd50414..db4a621a 100644
--- a/sphinx/themes/agogo/static/agogo.css_t
+++ b/sphinx/themes/agogo/static/agogo.css_t
@@ -467,7 +467,7 @@ div.viewcode-block:target {
     border-bottom: 1px solid #ac9;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     background-color: #ddd;
     color: #333;
     padding: 2px 5px;
diff --git a/sphinx/themes/basic/static/basic.css_t b/sphinx/themes/basic/static/basic.css_t
index d4561bfa..6fccb86e 100644
--- a/sphinx/themes/basic/static/basic.css_t
+++ b/sphinx/themes/basic/static/basic.css_t
@@ -475,17 +475,17 @@ table.highlighttable td {
     padding: 0 0.5em 0 0.5em;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     padding: 2px 5px;
     font-size: small;
 }
 
-div.code-block-filename tt {
+div.code-block-caption tt {
     background-color: transparent;
 }
 
-div.code-block-filename + pre,
-div.code-block-filename + div.highlight > pre {
+div.code-block-caption + pre,
+div.code-block-caption + div.highlight > pre {
     margin-top: 0;
 }
 
diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t
index ae4012d0..1493c5d9 100644
--- a/sphinx/themes/default/static/default.css_t
+++ b/sphinx/themes/default/static/default.css_t
@@ -309,7 +309,7 @@ div.viewcode-block:target {
     border-bottom: 1px solid #ac9;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     color: #efefef;
     background-color: #1c4e63;
 }
diff --git a/sphinx/themes/nature/static/nature.css_t b/sphinx/themes/nature/static/nature.css_t
index 7909e813..09573ead 100644
--- a/sphinx/themes/nature/static/nature.css_t
+++ b/sphinx/themes/nature/static/nature.css_t
@@ -244,7 +244,7 @@ div.viewcode-block:target {
     border-bottom: 1px solid #ac9;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     background-color: #ddd;
     color: #222;
     border: 1px solid #C6C9CB;
diff --git a/sphinx/themes/pyramid/static/pyramid.css_t b/sphinx/themes/pyramid/static/pyramid.css_t
index 053f61fa..dc015bb9 100644
--- a/sphinx/themes/pyramid/static/pyramid.css_t
+++ b/sphinx/themes/pyramid/static/pyramid.css_t
@@ -341,7 +341,7 @@ tt.xref {
     font-style: normal;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     background-color: #ddd;
     color: #222;
 }
diff --git a/sphinx/themes/sphinxdoc/static/sphinxdoc.css_t b/sphinx/themes/sphinxdoc/static/sphinxdoc.css_t
index 9f90d56f..cd781d29 100644
--- a/sphinx/themes/sphinxdoc/static/sphinxdoc.css_t
+++ b/sphinx/themes/sphinxdoc/static/sphinxdoc.css_t
@@ -338,7 +338,7 @@ div.viewcode-block:target {
     border-bottom: 1px solid #ac9;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     background-color: #ddd;
     color: #222;
     border: 1px solid #ccc;
diff --git a/sphinx/themes/traditional/static/traditional.css_t b/sphinx/themes/traditional/static/traditional.css_t
index 4b6e5c41..9a5d56dc 100644
--- a/sphinx/themes/traditional/static/traditional.css_t
+++ b/sphinx/themes/traditional/static/traditional.css_t
@@ -703,6 +703,6 @@ div.viewcode-block:target {
     padding: 0 10px;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     background-color: #cceeff;
 }
diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py
index 2d336692..b856da06 100644
--- a/sphinx/writers/html.py
+++ b/sphinx/writers/html.py
@@ -275,9 +275,9 @@ class HTMLTranslator(BaseTranslator):
             **highlight_args)
         starttag = self.starttag(node, 'div', suffix='',
                                  CLASS='highlight-%s' % lang)
-        if 'filename' in node:
-            starttag += '<div class="code-block-filename"><tt>%s</tt></div>' % (
-                node['filename'],)
+        if 'caption' in node:
+            starttag += '<div class="code-block-caption"><tt>%s</tt></div>' % (
+                node['caption'],)
         self.body.append(starttag + highlighted + '</div>\n')
         raise nodes.SkipNode
 
diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
index d77c2c54..a7459c92 100644
--- a/sphinx/writers/latex.py
+++ b/sphinx/writers/latex.py
@@ -1345,11 +1345,11 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 highlight_args['force'] = True
             if 'linenos' in node:
                 linenos = node['linenos']
-            filename = node.get('filename')
-            if filename:
+            caption = node.get('caption')
+            if caption:
                 self.body.append('\n{\\colorbox[rgb]{0.9,0.9,0.9}'
                                  '{\\makebox[\\textwidth][l]'
-                                 '{\\small\\texttt{%s}}}}\n' % (filename,))
+                                 '{\\small\\texttt{%s}}}}\n' % (caption,))
             def warner(msg):
                 self.builder.warn(msg, (self.curfilestack[-1], node.line))
             hlcode = self.highlighter.highlight_block(code, lang, warn=warner,
diff --git a/tests/roots/test-directive-code/caption.rst b/tests/roots/test-directive-code/caption.rst
new file mode 100644
index 00000000..274d0f19
--- /dev/null
+++ b/tests/roots/test-directive-code/caption.rst
@@ -0,0 +1,21 @@
+Dedent
+======
+
+Code blocks
+-----------
+
+.. code-block:: ruby
+   :caption: caption-test.rb
+
+   def ruby?
+       false
+   end
+
+
+Literal Include
+---------------
+
+.. literalinclude:: literal.inc
+   :language: python
+   :caption: caption-test.py
+   :lines: 10-11
diff --git a/tests/roots/test-directive-code/index.rst b/tests/roots/test-directive-code/index.rst
index ac7e519e..dab6b708 100644
--- a/tests/roots/test-directive-code/index.rst
+++ b/tests/roots/test-directive-code/index.rst
@@ -2,6 +2,7 @@ test-directive-code
 ===================
 
 .. toctree::
+   :glob:
 
    *
 
diff --git a/tests/test_directive_code.py b/tests/test_directive_code.py
index bc2609df..4c02466d 100644
--- a/tests/test_directive_code.py
+++ b/tests/test_directive_code.py
@@ -77,6 +77,27 @@ def test_code_block_dedent(app):
     assert actual == '\n\n'

 

 

+@with_app(buildername='html',

+          srcdir=(test_roots / 'test-directive-code'),

+          _copy_to_temp=True)

+def test_code_block_caption_html(app):

+    app.builder.build('index')

+    html = (app.outdir / 'caption.html').text()

+    caption = '<div class="code-block-caption"><tt>caption-test.rb</tt></div>'

+    assert caption in html

+

+

+@with_app(buildername='latex',

+          srcdir=(test_roots / 'test-directive-code'),

+          _copy_to_temp=True)

+def test_code_block_caption_latex(app):

+    app.builder.build('index')

+    latex = (app.outdir / 'Python.tex').text()

+    caption = ('{\\colorbox[rgb]{0.9,0.9,0.9}{\\makebox[\\textwidth][l]'

+               '{\\small\\texttt{caption-test.rb}}}}')

+    assert caption in latex

+

+

 @with_app(buildername='xml',

           srcdir=(test_roots / 'test-directive-code'),

           _copy_to_temp=True)

@@ -129,3 +150,24 @@ def test_literal_include_dedent(app):
 

     actual = get_dedent_actual(1000)

     assert actual == '\n\n'

+

+

+@with_app(buildername='html',

+          srcdir=(test_roots / 'test-directive-code'),

+          _copy_to_temp=True)

+def test_literalinclude_caption_html(app):

+    app.builder.build('index')

+    html = (app.outdir / 'caption.html').text()

+    caption = '<div class="code-block-caption"><tt>caption-test.py</tt></div>'

+    assert caption in html

+

+

+@with_app(buildername='latex',

+          srcdir=(test_roots / 'test-directive-code'),

+          _copy_to_temp=True)

+def test_literalinclude_caption_latex(app):

+    app.builder.build('index')

+    latex = (app.outdir / 'Python.tex').text()

+    caption = ('{\\colorbox[rgb]{0.9,0.9,0.9}{\\makebox[\\textwidth][l]'

+               '{\\small\\texttt{caption-test.py}}}}')

+    assert caption in latex