def run(self):
        code = u'\n'.join(self.content)

        linespec = self.options.get('emphasize-lines')
        if linespec:
            try:
                nlines = len(self.content)
                hl_lines = [x+1 for x in parselinenos(linespec, nlines)]
            except ValueError as err:
                document = self.state.document
                return [document.reporter.warning(str(err), line=self.lineno)]
        else:
            hl_lines = None

        literal = nodes.literal_block(code, code)
        literal['language'] = self.arguments[0]
        filename = self.options.get('filename')
        if filename:
            literal['filename'] = filename
        literal['linenos'] = 'linenos' in self.options or \
                             'lineno-start' in self.options
        extra_args = literal['highlight_args'] = {}
        if hl_lines is not None:
            extra_args['hl_lines'] = hl_lines
        if 'lineno-start' in self.options:
            extra_args['linenostart'] = self.options['lineno-start']
        set_source_info(self, literal)
        return [literal]

 def run(self):
     node = ifconfig()
     node.document = self.state.document
     set_source_info(self, node)
     node["expr"] = self.arguments[0]
     self.state.nested_parse(self.content, self.content_offset, node, match_titles=1)
     return [node]

 def run(self):
     node = addnodes.versionmodified()
     node.document = self.state.document
     set_source_info(self, node)
     node['type'] = self.name
     node['version'] = self.arguments[0]
     text = versionlabels[self.name] % self.arguments[0]
     if len(self.arguments) == 2:
         inodes, messages = self.state.inline_text(self.arguments[1],
                                                   self.lineno+1)
         para = nodes.paragraph(self.arguments[1], '', *inodes)
         set_source_info(self, para)
         node.append(para)
     else:
         messages = []
     if self.content:
         self.state.nested_parse(self.content, self.content_offset, node)
     if len(node):
         if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
             content = nodes.inline(node[0].rawsource, translatable=True)
             content.source = node[0].source
             content.line = node[0].line
             content += node[0].children
             node[0].replace_self(nodes.paragraph('', '', content))
         node[0].insert(0, nodes.inline('', '%s: ' % text,
                                        classes=['versionmodified']))
     else:
         para = nodes.paragraph('', '',
                                nodes.inline('', '%s.' % text,
                                             classes=['versionmodified']))
         node.append(para)
     env = self.state.document.settings.env
     # XXX should record node.source as well
     env.note_versionchange(node['type'], node['version'], node, node.line)
     return [node] + messages

    def run(self):
        visual_node = visual(is_figure=False)
        set_source_info(self, visual_node)
        set_type_info(self, visual_node)

        visual_node['docname'], visual_node['visualid'] = self.get_visual_id_info()
        self.options['name'] = visual_node['visualid']
        self.add_name(visual_node)

        self.emit('visual-node-inited', self, visual_node)

        caption = self.get_caption()
        legend, visual_node['content_block'] = self.get_legend_and_visual_content()
        if caption is not None or legend is not None:
            visual_node['is_figure'] = True

        self.emit('visual-caption-and-legend-extracted', self, visual_node, caption, legend)

        if visual_node['type'] == 'photo':
            uri = self.get_temp_image_uri()
            self.run_figure_or_image_with_uri(uri, visual_node, caption, legend)
            # Replacing image node is not a good option, but we could manipulate uri.
            # for image_node in visual_node.traverse(condition=nodes.image):
            #     image_node['uri'] = something

            # By default, assume it doesn't need a placeholder. Later processing can change this.
            visual_node['placeholder'] = False
        elif visual_node['type'] == 'video':
            raise NotImplementedError('Visuals does not support videos yet')
        else:
            raise NotImplementedError('Visuals does not support link or rich oembed content yet')

        self.emit('visual-node-generated', self, visual_node)

        return [visual_node]

    def run(self):

        env = self.state.document.settings.env
        app = env.app

        # filename *or* python code content, but not both
        if self.arguments and self.content:
            raise SphinxError("bokeh-plot:: directive can't have both args and content")

        # process inline examples here
        if self.content:
            app.debug("[bokeh-plot] handling inline example in %r", env.docname)
            source = '\n'.join(self.content)
            # need docname not to look like a path
            docname = env.docname.replace("/", "-")
            serialno = env.new_serialno(env.docname)
            js_name = "bokeh-plot-%s-inline-%d.js" % (docname, serialno)
            # the code runner just needs a real path to cd to, this will do
            path = join(env.bokeh_plot_auxdir, js_name)

            (script, js, js_path, source) = _process_script(source, path, env.bokeh_plot_auxdir, js_name)
            env.bokeh_plot_files[js_name] = (script, js, js_path, source)

        # process example files here
        else:
            example_path = self.arguments[0][:-3]  # remove the ".py"

            # if it's an "internal" example, the python parser has already handled it
            if example_path in env.bokeh_plot_files:
                app.debug("[bokeh-plot] handling internal example in %r: %s", env.docname, self.arguments[0])
                (script, js, js_path, source) = env.bokeh_plot_files[example_path]

            # handle examples external to the docs source, e.g. gallery examples
            else:
                app.debug("[bokeh-plot] handling external example in %r: %s", env.docname, self.arguments[0])
                source = open(self.arguments[0]).read()
                source = decode_utf8(source)
                docname = env.docname.replace("/", "-")
                serialno = env.new_serialno(env.docname)
                js_name = "bokeh-plot-%s-external-%d.js" % (docname, serialno)
                (script, js, js_path, source) = _process_script(source, self.arguments[0], env.bokeh_plot_auxdir, js_name)
                env.bokeh_plot_files[js_name] = (script, js, js_path, source)

        # use the source file name to construct a friendly target_id
        target_id = "%s.%s" % (env.docname, basename(js_path))
        target = nodes.target('', '', ids=[target_id])
        result = [target]

        code = nodes.literal_block(source, source, language="python", linenos=False, classes=[])
        set_source_info(self, code)

        source_position = self.options.get('source-position', 'below')

        if source_position == "above": result += [code]

        result += [nodes.raw('', script, format="html")]

        if source_position == "below": result += [code]

        return result

    def add_auto_version_changed(self, node):
        """Add a version_node to document a version change to ``node``.

        Add the new node at the end of ``node``.

        """
        symbol = self.lookup_auto_symbol()
        if not symbol:
            return
        package, version = symbol.properties.get(
            'custom-package-version', ('', ''))
        if version:
            version_node = addnodes.versionmodified()
            version_node.document = self.state.document
            set_source_info(self, version_node)
            version_node['type'] = 'versionchanged'
            version_node['version'] = version
            msg = self.VERSION_CHANGE_LABEL.format(
                objtype=self.object_type.lname, version=version,
                package=package)
            msg_node = corenodes.inline('', msg, classes=['versionmodified'])
            version_node.append(corenodes.paragraph('', '', msg_node))
            env = self.state.document.settings.env
            env.note_versionchange(
                version_node['type'], version_node['version'],
                version_node, version_node.line)
            node.append(version_node)
            return node

    def run(self):

        document = self.state.document
        if not document.settings.file_insertion_enabled:
            return [document.reporter.warning('File insertion disabled', line=self.lineno)]
        env = document.settings.env
        relative_filename, filename = env.relfn2path(self.arguments[0])

        encoding = self.options.get('encoding', env.config.source_encoding)
        codec_info = codecs.lookup(encoding)
        try:
            f = codecs.StreamReaderWriter(open(filename, 'rb'),
                                          codec_info[2], codec_info[3], 'strict')
            text = f.read() # file content
            f.close()
        except (IOError, OSError):
            return [document.reporter.warning('Include file %r not found or reading it failed' % filename,
                                              line=self.lineno)]
        except UnicodeError:
            return [document.reporter.warning('Encoding %r used for reading included file %r seems to '
                                              'be wrong, try giving an :encoding: option' %
                                              (encoding, filename))]

        retnode = GetTheCode(text, text, source=filename, filename=None)
        set_source_info(self, retnode)
        if self.options.get('language', ''):
            retnode['language'] = self.options['language']
        if 'linenos' in self.options:
            retnode['linenos'] = True
        if 'hidden' in self.options:
            retnode['hidden'] = True
        env.note_dependency(relative_filename)

        return [retnode]

    def make_title(self):
        # type: () -> Tuple[nodes.Node, unicode]
        title, message = tables.ListTable.make_title(self)
        if title:
            set_source_info(self, title)

        return title, message

    def make_title(self):
        # type: () -> Tuple[nodes.title, List[nodes.system_message]]
        title, message = super().make_title()
        if title:
            set_source_info(self, title)

        return title, message

    def run(self):
        filename = self.arguments[0]

        cwd = os.getcwd()
        os.chdir(TMPDIR)

        parts = []
        try:
            code = AsdfFile.read(filename, _get_yaml_content=True)
            code = '{0}{1}\n'.format(ASDF_MAGIC, version_string) + code.strip().decode('utf-8')
            literal = nodes.literal_block(code, code)
            literal['language'] = 'yaml'
            set_source_info(self, literal)
            parts.append(literal)

            ff = AsdfFile.read(filename)
            for i, block in enumerate(ff.blocks.internal_blocks):
                data = codecs.encode(block.data.tostring(), 'hex')
                if len(data) > 40:
                    data = data[:40] + '...'.encode()
                allocated = block._allocated
                size = block._size
                data_size = block._data_size
                flags = block._flags

                if flags & BLOCK_FLAG_STREAMED:
                    allocated = size = data_size = 0

                lines = []
                lines.append('BLOCK {0}:'.format(i))

                human_flags = []
                for key, val in FLAGS.items():
                    if flags & key:
                        human_flags.append(val)
                if len(human_flags):
                    lines.append('    flags: {0}'.format(' | '.join(human_flags)))
                if block.compression:
                    lines.append('    compression: {0}'.format(block.compression))
                lines.append('    allocated_size: {0}'.format(allocated))
                lines.append('    used_size: {0}'.format(size))
                lines.append('    data_size: {0}'.format(data_size))
                lines.append('    data: {0}'.format(data))

                code = '\n'.join(lines)

                literal = nodes.literal_block(code, code)
                literal['language'] = 'yaml'
                set_source_info(self, literal)
                parts.append(literal)

        finally:
            os.chdir(cwd)

        result = nodes.admonition()
        textnodes, messages = self.state.inline_text(filename, self.lineno)
        title = nodes.title(filename, '', *textnodes)
        result += title
        result.children.extend(parts)
        return [result]

    def run(self):
        # type: () -> List[nodes.Node]
        self.assert_has_content()

        code = '\n'.join(self.content)
        node = nodes.literal_block(code, code,
                                   classes=self.options.get('classes', []),
                                   highlight_args={})
        self.add_name(node)
        set_source_info(self, node)

        if self.arguments:
            # highlight language specified
            node['language'] = self.arguments[0]
            node['force_highlighting'] = True
        else:
            # no highlight language specified.  Then this directive refers the current
            # highlight setting via ``highlight`` directive or ``highlight_language``
            # configuration.
            node['language'] = self.env.temp_data.get('highlight_language',
                                                      self.config.highlight_language)
            node['force_highlighting'] = False

        if 'number-lines' in self.options:
            node['linenos'] = True

            # if number given, treat as lineno-start.
            if self.options['number-lines']:
                node['highlight_args']['linenostart'] = self.options['number-lines']

        return [node]

 def run(self):
     r'''Executes the directive.
     '''
     from abjad import abjad_configuration
     self.assert_has_content()
     os.chdir(abjad_configuration.abjad_directory)
     result = []
     for line in self.content:
         curdir = os.path.basename(os.path.abspath(os.path.curdir))
         prompt = '{}$ '.format(curdir)
         prompt += line
         result.append(prompt)
         process = subprocess.Popen(
             line,
             shell=True,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             )
         stdout = self._read_from_pipe(process.stdout)
         stderr = self._read_from_pipe(process.stderr)
         result.append(stdout)
         result.append(stderr)
     code = '\n'.join(result)
     literal = nodes.literal_block(code, code)
     literal['language'] = 'console'
     set_source_info(self, literal)
     return [literal]

    def run(self):
        language = self.arguments[0]

        indexed_languages = self.options.get('index_as') or language
        index_specs = ['pair: {}; language'.format(l)
                       for l in indexed_languages.splitlines()]

        name = nodes.fully_normalize_name(language)
        target = 'language-{}'.format(name)
        targetnode = nodes.target('', '', ids=[target])
        self.state.document.note_explicit_target(targetnode)

        indexnode = addnodes.index()
        indexnode['entries'] = []
        indexnode['inline'] = False
        set_source_info(self, indexnode)
        for spec in index_specs:
            indexnode['entries'].extend(process_index_entry(spec, target))

        sectionnode = nodes.section()
        sectionnode['names'].append(name)

        title, messages = self.state.inline_text(language, self.lineno)
        titlenode = nodes.title(language, '', *title)

        sectionnode += titlenode
        sectionnode += messages
        self.state.document.note_implicit_target(sectionnode, sectionnode)

        self.state.nested_parse(self.content, self.content_offset, sectionnode)

        return [indexnode, targetnode, sectionnode]

    def run(self):
        code = u'\n'.join(self.content)

        linespec = self.options.get('emphasize-lines')
        if linespec:
            try:
                nlines = len(self.content)
                hl_lines = [x+1 for x in parselinenos(linespec, nlines)]
            except ValueError as err:
                document = self.state.document
                return [document.reporter.warning(str(err), line=self.lineno)]
        else:
            hl_lines = None

        if 'dedent' in self.options:
            lines = code.split('\n')
            lines = dedent_lines(lines, self.options['dedent'])
            code = '\n'.join(lines)

        literal = nodes.literal_block(code, code)
        literal['language'] = self.arguments[0]
        literal['linenos'] = 'linenos' in self.options or \
                             'lineno-start' in self.options
        extra_args = literal['highlight_args'] = {}
        if hl_lines is not None:
            extra_args['hl_lines'] = hl_lines
        if 'lineno-start' in self.options:
            extra_args['linenostart'] = self.options['lineno-start']
        set_source_info(self, literal)

        caption = self.options.get('caption')
        if caption:
            literal = container_wrapper(self, literal, caption)

        return [literal]

    def run(self):
        from docutils import nodes
        from sphinx import addnodes
        from sphinx.util.nodes import set_source_info

        node = addnodes.only()
        node.document = self.state.document
        set_source_info(self, node)
        node['expr'] = self.arguments[0]

        # hack around title style bookkeeping
        surrounding_title_styles = self.state.memo.title_styles
        surrounding_section_level = self.state.memo.section_level
        self.state.memo.title_styles = []
        self.state.memo.section_level = 0
        try:
            result = self.state.nested_parse(self.content, 0, node,
                                             match_titles=1)
            depth = len(surrounding_title_styles)
            if self.state.memo.title_styles:
                style = self.state.memo.title_styles[0]
                if style in surrounding_title_styles:
                    depth = surrounding_title_styles.index(style)
            parent = self.state.parent
            for i in xrange(len(surrounding_title_styles) - depth):
                if parent.parent:
                    parent = parent.parent
            parent.append(node)
        finally:
            self.state.memo.title_styles = surrounding_title_styles
            self.state.memo.section_level = surrounding_section_level
        return []

    def run(self):
        document = self.state.document
        env = document.settings.env
        docname = env.docname

        if ':' in self.name:
            self.domain, self.objtype = self.name.split(':', 1)
        else:
            self.domain, self.objtype = 'py', self.name

        key = self.find_key(self.content.parent)

        targetnode = nodes.target('', '', ids=[key])

        key_elem = keynode(key)

        # Separating argument and content causes two <dd>-s to be generated in
        # the same <dl>
        doc = addnodes.desc_content()
        update_attrs(doc, self)
        txt = '\n'.join(self.arguments)
        self.before_content()
        details = keydoc(self.state, self.content)
        update_attrs(details, self)
        DocFieldTransformer(self).transform_all(details)
        self.after_content()
        doc += nodes.paragraph(txt, txt)
        doc += details

        import os
        source_line = self.lineno
        source, _ = self.state_machine.get_source_and_line(source_line)
        src_file, src_other = source.split(':', 1)
        source_file = os.path.basename(src_file)

        doc_entry = ibkey(self, key, key_elem, doc)
        #doc_entry = make_admonition(dummy, self.name, 'Alma', self.options, self.content, self.lineno, self.content_offset, self.block_text, self.state, self.state_machine)[0]
        
        catalog_entry = iblist_entry(
            self,
            env, docname, src_other, source_file, source_line,
            key, key_elem, doc)

        set_source_info(self, doc_entry)
        set_source_info(self, catalog_entry)
        env.resolve_references(doc_entry, docname, env.app.builder)
        env.resolve_references(catalog_entry, docname, env.app.builder)

        if not hasattr(env, 'ibkey_all_ibkeys'):
            env.ibkey_all_ibkeys = dict()

        env.ibkey_all_ibkeys[key] = dict(docname=docname,
                                         catalog_entry=catalog_entry)

        # - super.run() doesnt't kill the structure, it works fine
        # - returning both superrun and doc_entry does (in any order)
        # - The todo in the method docstring is rendered outside the 
        #   method's documentation (?!)
        return [doc_entry] #[targetnode, doc_entry]

 def run(self):
     r'''Executes the directive.
     '''
     from abjad.tools import abjadbooktools
     block = abjadbooktools.abjad_reveal_block()
     block['reveal-label'] = self.arguments[0]
     set_source_info(self, block)
     return [block]

 def run(self):
     node = addnodes.only()
     node.document = self.state.document
     set_source_info(self, node)
     node['expr'] = self.arguments[0]
     self.state.nested_parse(self.content, self.content_offset, node,
                             match_titles=1)
     return [node]

    def run(self):

        node = nextslide(**self.options)
        node.args = self.arguments
        node.document = self.state.document
        set_source_info(self, node)

        return [node]

    def run(self):
        code = '\n'.join(self.content)

        literal = snippet_with_filename(code, code)
        if self.arguments:
            literal['language'] = self.arguments[0]
        literal['filename'] = self.options['filename']
        set_source_info(self, literal)
        return [literal]