Merged in tk0miya/sphinx (pull request #266)

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

sphinx/directives/code.py

@@ -77,7 +77,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):
@@ -101,9 +101,9 @@ class CodeBlock(Directive):
 
         literal = nodes.literal_block(code, code)
         literal['language'] = self.arguments[0]
-        filename = self.options.get('filename')
+        caption = self.options.get('caption')
-        if filename:
+        if caption:
-            literal['filename'] = filename
+            literal['caption'] = caption
         literal['linenos'] = 'linenos' in self.options or \
                              'lineno-start' in self.options
         extra_args = literal['highlight_args'] = {}
@@ -140,7 +140,7 @@ class LiteralInclude(Directive):
         'prepend': directives.unchanged_required,
         'append': directives.unchanged_required,
         'emphasize-lines': directives.unchanged_required,
-        'filename': directives.unchanged,
+        'caption': directives.unchanged,
         'diff': directives.unchanged_required,
     }
 
@@ -269,11 +269,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')
+        caption = self.options.get('caption')
-        if filename is not None:
+        if caption is not None:
-            if not filename:
+            if not caption:
-                filename = self.arguments[0]
+                caption = self.arguments[0]
-            retnode['filename'] = filename
+            retnode['caption'] = caption
         extra_args = retnode['highlight_args'] = {}
         if hl_lines is not None:
             extra_args['hl_lines'] = hl_lines

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;

sphinx/themes/basic/static/basic.css_t

@@ -475,7 +475,7 @@ table.highlighttable td {
     padding: 0 0.5em 0 0.5em;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     padding: 2px 5px;
     font-size: small;
 }
@@ -484,8 +484,8 @@ div.code-block-filename code {
     background-color: transparent;
 }
 
-div.code-block-filename + pre,
+div.code-block-caption + pre,
-div.code-block-filename + div.highlight > pre {
+div.code-block-caption + div.highlight > pre {
     margin-top: 0;
 }
 

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;
 }

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;

sphinx/themes/pyramid/static/pyramid.css_t

@@ -341,7 +341,7 @@ code.xref {
     font-style: normal;
 }
 
-div.code-block-filename {
+div.code-block-caption {
     background-color: #ddd;
     color: #222;
 }

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;

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;
 }

sphinx/writers/html.py

@@ -283,9 +283,9 @@ class HTMLTranslator(BaseTranslator):
             **highlight_args)
         starttag = self.starttag(node, 'div', suffix='',
                                  CLASS='highlight-%s' % lang)
-        if 'filename' in node:
+        if 'caption' in node:
-            starttag += '<div class="code-block-filename"><code>%s</code></div>' % (
+            starttag += '<div class="code-block-caption"><code>%s</code></div>' % (
-                node['filename'],)
+                node['caption'],)
         self.body.append(starttag + highlighted + '</div>\n')
         raise nodes.SkipNode
 

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')
+            caption = node.get('caption')
-            if filename:
+            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,

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

tests/roots/test-directive-code/index.rst

@@ -2,6 +2,7 @@ test-directive-code
 ===================
 
 .. toctree::
+   :glob:
 
    *
 

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"><code>caption-test.rb</code></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"><code>caption-test.py</code></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