Add caption to code-block directive in Sphinx.

conf.py

import sys
sys.path.insert(0, 'source/')
extensions += ['mycodeblock']

language = 'ja'

latex_elements['preamble'] = '\\usepackage{ascmac}'
latex_docclass = {
    'manual': 'jsbook'
}

literal_code_block_caption.css

p.caption {
    margin: 0;
    font-size: 0.75em;
    font-weight: bold;
}

div.caption-code > div > div.highlight > pre {
    margin-top: 0;
}

mycodeblock.py

# -*- coding: utf-8 -*-
import os
from docutils import nodes
from docutils.parsers.rst import directives
from sphinx.directives.code import CodeBlock


class literal_block_caption(nodes.General, nodes.Element):
    pass


class CaptionedCodeBlock(CodeBlock):
    option_spec = {
        'linenos': directives.flag,
        'caption': directives.unchanged,
        'emphasize-lines': directives.unchanged_required,
    }

    def run(self):
        ret = super(CaptionedCodeBlock, self).run()
        caption = self.options.get('caption')
        if caption and isinstance(ret[0], nodes.literal_block):
            caption_node = literal_block_caption('', ret[0])
            caption_node['caption'] = caption
            ret[0] = caption_node

        return ret


def html_visit_literal_block_caption(self, node):
    self.body.append(self.starttag(node, 'div', CLASS='caption-code'))
    self.body.append(self.starttag(node, 'p', '', CLASS='caption'))

    prefix = self.builder.config.code_block_caption_prefix
    if prefix:
        self.body.append("%s: " % prefix)

    self.body.append(node['caption'])
    self.body.append('</p>\n')


def html_depart_literal_block_caption(self, node):
    self.body.append('</div>')


def latex_visit_literal_block_caption(self, node):
    prefix = self.builder.config.code_block_caption_prefix
    if prefix:
        self.body.append('\\begin{itembox}[c]{%s: %s}' % (prefix, node['caption']))
    else:
        self.body.append('\\begin{itembox}[c]{%s}' % node['caption'])


def latex_depart_literal_block_caption(self, node):
    self.body.append('\\end{itembox}')


def on_builder_inited(app):
    css_dir = os.path.join(os.path.dirname(__file__), 'css')
    app.config.html_static_path.append(os.path.relpath(css_dir, app.confdir))

    app.add_stylesheet('literal_code_block_caption.css')


def setup(app):
    directives._directives.pop('code-block', None)  # uninstall sphinx's

    app.add_node(literal_block_caption,
                 html=(html_visit_literal_block_caption,
                       html_depart_literal_block_caption),
                 latex=(latex_visit_literal_block_caption,
                        latex_depart_literal_block_caption))
    app.add_directive('code-block', CaptionedCodeBlock)
    app.add_config_value('code_block_caption_prefix', 'List', 'html')
    app.connect('builder-inited', on_builder_inited)