def glossary_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    """Glossary with cross-reference targets for :term: roles."""
    env = state.document.settings.env
    node = addnodes.glossary()
    state.nested_parse(content, content_offset, node)

    # the content should be definition lists
    dls = [child for child in node if isinstance(child, nodes.definition_list)]
    # now, extract definition terms to enable cross-reference creation
    for dl in dls:
        dl['classes'].append('glossary')
        for li in dl.children:
            if not li.children or not isinstance(li[0], nodes.term):
                continue
            termtext = li.children[0].astext()
            new_id = 'term-' + nodes.make_id(termtext)
            if new_id in env.gloss_entries:
                new_id = 'term-' + str(len(env.gloss_entries))
            env.gloss_entries.add(new_id)
            li[0]['names'].append(new_id)
            li[0]['ids'].append(new_id)
            state.document.settings.env.note_reftarget('term', termtext.lower(),
                                                       new_id)
            # add an index entry too
            indexnode = addnodes.index()
            indexnode['entries'] = [('single', termtext, new_id, termtext)]
            li.insert(0, indexnode)
    return [node]

def module_directive(name, arguments, options, content, lineno,
                     content_offset, block_text, state, state_machine):
    env = state.document.settings.env
    modname = arguments[0].strip()
    noindex = 'noindex' in options
    env.currmodule = modname
    env.note_module(modname, options.get('synopsis', ''),
                    options.get('platform', ''),
                    'deprecated' in options)
    modulenode = addnodes.module()
    modulenode['modname'] = modname
    modulenode['synopsis'] = options.get('synopsis', '')
    targetnode = nodes.target('', '', ids=['module-' + modname])
    state.document.note_explicit_target(targetnode)
    ret = [modulenode, targetnode]
    if 'platform' in options:
        modulenode['platform'] = options['platform']
        node = nodes.paragraph()
        node += nodes.emphasis('', _('Platforms: '))
        node += nodes.Text(options['platform'], options['platform'])
        ret.append(node)
    # the synopsis isn't printed; in fact, it is only used in the modindex currently
    if not noindex:
        indextext = _('%s (module)') % modname
        inode = addnodes.index(entries=[('single', indextext,
                                         'module-' + modname, modname)])
        ret.insert(0, inode)
    return ret

def index_directive(name, arguments, options, content, lineno,
                    content_offset, block_text, state, state_machine):
    arguments = arguments[0].split('\n')
    env = state.document.settings.env
    targetid = 'index-%s' % env.index_num
    env.index_num += 1
    targetnode = nodes.target('', '', ids=[targetid])
    state.document.note_explicit_target(targetnode)
    indexnode = addnodes.index()
    indexnode['entries'] = ne = []
    for entry in arguments:
        entry = entry.strip()
        for type in pairindextypes:
            if entry.startswith(type+':'):
                value = entry[len(type)+1:].strip()
                value = pairindextypes[type] + '; ' + value
                ne.append(('pair', value, targetid, value))
                break
        else:
            for type in indextypes:
                if entry.startswith(type+':'):
                    value = entry[len(type)+1:].strip()
                    ne.append((type, value, targetid, value))
                    break
            # shorthand notation for single entries
            else:
                for value in entry.split(','):
                    value = value.strip()
                    if not value:
                        continue
                    ne.append(('single', value, targetid, value))
    return [indexnode, targetnode]

    def run(self):
        env = self.state.document.settings.env
        # normalize whitespace in fullname like XRefRole does
        fullname = ws_re.sub(' ', self.arguments[0].strip())
        targetname = '%s-%s' % (self.ref_type, fullname)

        # keep the target; this may be used to generate a BBIndex later
        targets = env.domaindata['bb']['targets'].setdefault(self.ref_type, {})
        targets[fullname] = env.docname, targetname

        # make up the descriptor: a target and potentially an index descriptor
        node = nodes.target('', '', ids=[targetname])
        ret = [node]

        # add the target to the document
        self.state.document.note_explicit_target(node)

        # append the index node if necessary
        entries = []
        for tpl in self.indextemplates:
            colon = tpl.find(':')
            if colon != -1:
                indextype = tpl[:colon].strip()
                indexentry = tpl[colon+1:].strip() % (fullname,)
            else:
                indextype = 'single'
                indexentry = tpl % (fullname,)
            entries.append((indextype, indexentry, targetname, targetname))

        if entries:
            inode = addnodes.index(entries=entries)
            ret.insert(0, inode)

        return ret 

def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    # create new reference target
    env = inliner.document.settings.env
    targetid = 'index-%s' % env.new_serialno('index')
    targetnode = nodes.target('', '', ids=[targetid])
    # split text and target in role content
    has_explicit_title, title, target = split_explicit_title(text)
    title = utils.unescape(title)
    target = utils.unescape(target)
    # if an explicit target is given, we can process it as a full entry
    if has_explicit_title:
        entries = process_index_entry(target, targetid)
    # otherwise we just create a "single" entry
    else:
        # but allow giving main entry
        main = ''
        if target.startswith('!'):
            target = target[1:]
            title = title[1:]
            main = 'main'
        entries = [('single', target, targetid, main)]
    indexnode = addnodes.index()
    indexnode['entries'] = entries
    set_role_source_info(inliner, lineno, indexnode)
    textnode = nodes.Text(title, title)
    return [indexnode, targetnode, textnode], []

    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
        #version = self.arguments[0]
        #summary = self.arguments[1]
        version, summary = text.split(':', 1)
        summary = summary.strip()
        
        indexstring = 'bareos-{}; {}'.format(version, summary)
        idstring = 'bareos-{}-{}'.format(version, summary)
        _id = nodes.make_id(idstring)
        
        # Generic index entries
        indexnode = addnodes.index()
        indexnode['entries'] = []

        indexnode['entries'].append([
            'pair',
            indexstring,
            _id, '', None
        ])

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

        #text_node = nodes.Text(text='Version >= {}'.format(version))
        #text_node = nodes.strong(text='Version >= {}'.format(version))
        text_node = nodes.emphasis(text='Version >= {}'.format(version))
        # target does not work with generated.
        #text_node = nodes.generated(text='Version >= {}'.format(version))
        
        return [targetnode, text_node, indexnode], []

    def run(self):
        env = self.state.document.settings.env
        node = addnodes.glossary()
        node.document = self.state.document
        self.state.nested_parse(self.content, self.content_offset, node)

        # the content should be definition lists
        dls = [child for child in node
               if isinstance(child, nodes.definition_list)]
        # now, extract definition terms to enable cross-reference creation
        new_dl = nodes.definition_list()
        new_dl['classes'].append('glossary')
        items = []
        for dl in dls:
            for li in dl.children:
                if not li.children or not isinstance(li[0], nodes.term):
                    continue
                termtext = li.children[0].astext()
                new_id = 'term-' + nodes.make_id(termtext)
                if new_id in env.gloss_entries:
                    new_id = 'term-' + str(len(env.gloss_entries))
                env.gloss_entries.add(new_id)
                li[0]['names'].append(new_id)
                li[0]['ids'].append(new_id)
                env.note_reftarget('term', termtext.lower(), new_id)
                # add an index entry too
                indexnode = addnodes.index()
                indexnode['entries'] = [('single', termtext, new_id, termtext)]
                li.insert(0, indexnode)
                items.append((termtext, li))
        if 'sorted' in self.options:
            items.sort(key=lambda x: x[0].lower())
        new_dl.extend(item[1] for item in items)
        node.children = [new_dl]
        return [node]

    def run(self):
        self.desctype = self.name
        self.env = self.state.document.settings.env
        self.indexnode = addnodes.index(entries=[])

        node = addnodes.desc()
        node.document = self.state.document
        node['desctype'] = self.desctype
        node['noindex'] = noindex = ('noindex' in self.options)

        self.names = []
        signatures = self.get_signatures()
        for i, sig in enumerate(signatures):
            # add a signature node for each signature in the current unit
            # and add a reference target for it
            signode = addnodes.desc_signature(sig, '')
            signode['first'] = False
            node.append(signode)
            try:
                # name can also be a tuple, e.g. (classname, objname)
                name = self.parse_signature(sig, signode)
            except ValueError, err:
                # signature parsing failed
                signode.clear()
                signode += addnodes.desc_name(sig, sig)
                continue  # we don't want an index entry here
            if not noindex and name not in self.names:
                # only add target and index entry if this is the first
                # description of the object with this name in this desc block
                self.names.append(name)
                self.add_target_and_index(name, sig, signode)

def indexmarkup_role(typ, rawtext, text, lineno, inliner,
                     options={}, content=[]):
    """Role for PEP/RFC references that generate an index entry."""
    env = inliner.document.settings.env
    if not typ:
        typ = env.config.default_role
    else:
        typ = typ.lower()
    has_explicit_title, title, target = split_explicit_title(text)  # type: bool, unicode, unicode  # NOQA
    title = utils.unescape(title)
    target = utils.unescape(target)
    targetid = 'index-%s' % env.new_serialno('index')
    indexnode = addnodes.index()
    targetnode = nodes.target('', '', ids=[targetid])
    inliner.document.note_explicit_target(targetnode)
    if typ == 'pep':
        indexnode['entries'] = [
            ('single', _('Python Enhancement Proposals; PEP %s') % target,
             targetid, '', None)]
        anchor = ''  # type: unicode
        anchorindex = target.find('#')
        if anchorindex > 0:
            target, anchor = target[:anchorindex], target[anchorindex:]
        if not has_explicit_title:
            title = "PEP " + utils.unescape(title)
        try:
            pepnum = int(target)
        except ValueError:
            msg = inliner.reporter.error('invalid PEP number %s' % target,
                                         line=lineno)
            prb = inliner.problematic(rawtext, rawtext, msg)
            return [prb], [msg]
        ref = inliner.document.settings.pep_base_url + 'pep-%04d' % pepnum
        sn = nodes.strong(title, title)
        rn = nodes.reference('', '', internal=False, refuri=ref+anchor,
                             classes=[typ])
        rn += sn
        return [indexnode, targetnode, rn], []
    elif typ == 'rfc':
        indexnode['entries'] = [
            ('single', 'RFC; RFC %s' % target, targetid, '', None)]
        anchor = ''
        anchorindex = target.find('#')
        if anchorindex > 0:
            target, anchor = target[:anchorindex], target[anchorindex:]
        if not has_explicit_title:
            title = "RFC " + utils.unescape(title)
        try:
            rfcnum = int(target)
        except ValueError:
            msg = inliner.reporter.error('invalid RFC number %s' % target,
                                         line=lineno)
            prb = inliner.problematic(rawtext, rawtext, msg)
            return [prb], [msg]
        ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
        sn = nodes.strong(title, title)
        rn = nodes.reference('', '', internal=False, refuri=ref+anchor,
                             classes=[typ])
        rn += sn
        return [indexnode, targetnode, rn], []

    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):
        # type: () -> List[nodes.Node]
        # normalize whitespace in fullname like XRefRole does
        fullname = ws_re.sub(' ', self.arguments[0].strip())
        targetname = '%s-%s' % (self.name, fullname)
        node = nodes.target('', '', ids=[targetname])
        self.state.document.note_explicit_target(node)
        ret = [node]  # type: List[nodes.Node]
        if self.indextemplate:
            indexentry = self.indextemplate % (fullname,)
            indextype = 'single'
            colon = indexentry.find(':')
            if colon != -1:
                indextype = indexentry[:colon].strip()
                indexentry = indexentry[colon + 1:].strip()
            inode = addnodes.index(entries=[(indextype, indexentry,
                                             targetname, '', None)])
            ret.insert(0, inode)
        name = self.name
        if ':' in self.name:
            _, name = self.name.split(':', 1)

        std = cast(StandardDomain, self.env.get_domain('std'))
        std.add_object(name, fullname, self.env.docname, targetname)

        return ret

 def run(self):
     env = self.state.document.settings.env
     modname = self.arguments[0].strip()
     noindex = 'noindex' in self.options
     env.temp_data['tcpip:module'] = modname
     env.domaindata['tcpip']['modules'][modname] = \
         (env.docname, self.options.get('synopsis', ''),
          self.options.get('platform', ''), 'deprecated' in self.options)
     targetnode = nodes.target('', '', ids=['module-' + modname], ismod=True)
     self.state.document.note_explicit_target(targetnode)
     ret = [targetnode]
     # XXX this behavior of the module directive is a mess...
     if 'platform' in self.options:
         platform = self.options['platform']
         node = nodes.paragraph()
         node += nodes.emphasis('', _('Platforms: '))
         node += nodes.Text(platform, platform)
         ret.append(node)
     # the synopsis isn't printed; in fact, it is only used in the
     # modindex currently
     if not noindex:
         indextext = _('%s (module)') % modname
         inode = addnodes.index(entries=[('single', indextext,
                                          'module-' + modname, modname)])
         ret.append(inode)
     return ret

 def run(self):
     # type: () -> List[nodes.Node]
     modname = self.arguments[0].strip()
     noindex = 'noindex' in self.options
     self.env.ref_context['py:module'] = modname
     ret = []
     if not noindex:
         self.env.domaindata['py']['modules'][modname] = (self.env.docname,
                                                          self.options.get('synopsis', ''),
                                                          self.options.get('platform', ''),
                                                          'deprecated' in self.options)
         # make a duplicate entry in 'objects' to facilitate searching for
         # the module in PythonDomain.find_obj()
         self.env.domaindata['py']['objects'][modname] = (self.env.docname, 'module')
         targetnode = nodes.target('', '', ids=['module-' + modname],
                                   ismod=True)
         self.state.document.note_explicit_target(targetnode)
         # the platform and synopsis aren't printed; in fact, they are only
         # used in the modindex currently
         ret.append(targetnode)
         indextext = _('%s (module)') % modname
         inode = addnodes.index(entries=[('single', indextext,
                                          'module-' + modname, '', None)])
         ret.append(inode)
     return ret

 def run(self):
     self.index_entries = []
     #~ index_entries is a list of 4-tuples of
     #~ ``(entrytype, entryname, target, ignored)``
     content = super(ActorDirective, self).run()
     indexnode = addnodes.index(entries=self.index_entries)
     return [indexnode] + content

 def run(self):
     arguments = self.arguments[0].split('\n')
     env = self.state.document.settings.env
     targetid = 'index-%s' % env.new_serialno('index')
     targetnode = nodes.target('', '', ids=[targetid])
     self.state.document.note_explicit_target(targetnode)
     indexnode = addnodes.index()
     indexnode['entries'] = ne = []
     for entry in arguments:
         entry = entry.strip()
         for type in pairindextypes:
             if entry.startswith(type+':'):
                 value = entry[len(type)+1:].strip()
                 value = pairindextypes[type] + '; ' + value
                 ne.append(('pair', value, targetid, value))
                 break
         else:
             for type in self.indextypes:
                 if entry.startswith(type+':'):
                     value = entry[len(type)+1:].strip()
                     if type == 'double':
                         type = 'pair'
                     ne.append((type, value, targetid, value))
                     break
             # shorthand notation for single entries
             else:
                 for value in entry.split(','):
                     value = value.strip()
                     if not value:
                         continue
                     ne.append(('single', value, targetid, value))
     return [indexnode, targetnode]

    def run(self):
        env = self.state.document.settings.env
        modname = self.arguments[0].strip()
        noindex = 'noindex' in self.options
        env.temp_data['lua:module'] = modname
        ret = []
        if not noindex:
            env.domaindata['lua']['modules'][modname] = \
                (env.docname, self.options.get('synopsis', ''),
                 self.options.get('platform', ''), 'deprecated' in self.options)

            ids = "lua-module.%s" % (modname)

            # make a duplicate entry in 'objects' to facilitate searching for
            # the module in LuaDomain.find_obj()
            env.domaindata['lua']['objects'][modname] = (env.docname, 'module', ids)
            targetnode = nodes.target('', '', ids=[ids],
                                      ismod=True)
            self.state.document.note_explicit_target(targetnode)
            # the platform and synopsis aren't printed; in fact, they are only
            # used in the modindex currently
            ret.append(targetnode)
            indextext = _('%s (module)') % modname
            inode = addnodes.index(entries=[('single', indextext,
                                             ids, '')])
            ret.append(inode)
        return ret

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

        env = self.state.document.settings.env
        env.temp_data['cf3:namespace'] = modname

        ret = []
        if 'noindex' in self.options:
            return ret

        env.domaindata['cf3']['namespaces'][modname] = (
            env.docname, self.options.get('synopsis', ''),
            'deprecated' in self.options,
        )
        targetnode = nodes.target(
            '', '', ids=['namespace-' + modname], ismod=True
        )
        self.state.document.note_explicit_target(targetnode)
        ret.append(targetnode)

        indextext = _('%s (namespace)') % modname
        ret.append(
            addnodes.index(entries=[
                ('single', indextext, 'namespace-' + modname, modname)
            ])
        )

        return ret

    def run(self):
        pkgname = self.arguments[0].strip()
        env = self.state.document.settings.env
        env.ref_context['qbs:package'] = pkgname

        if 'noindex' in self.options:
            return []

        sdkname = self.options.get('sdk', env.ref_context.get('qbs:sdk', None))

        if sdkname:
            pkgname = sdkname + '.' + pkgname

        env.domaindata['qbs']['packages'][pkgname] = (env.docname, self.options.get('synopsis', ''))
        env.domaindata['qbs']['objects'][pkgname] = (env.docname, 'package')

        # target
        targetname = 'package-' + pkgname
        targetnode = nodes.target('', '', ids=[targetname], ismod=True)
        self.state.document.note_explicit_target(targetnode)

        # index
        if sdkname:
            itext = _('%s (Qbs Package in %s)') % (pkgname[len(sdkname) + 1:], sdkname)
        else:
            itext = _('%s (Qbs Package') % (pkgname[len(sdkname) + 1:])
        inode = addnodes.index(entries=[('single', itext, targetname, '', None)])

        return [targetnode, inode]

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

        name = self.content[0].strip()
        expr = '\n'.join(self.content[1:]).strip()

        targetid = "syntax-%s" % name
        targetnode = nodes.target('', '', ids=[targetid])
        label = nodes.paragraph('', '', nodes.strong(text=name))
        ix = addnodes.index(entries=[
            ("single", "syntax; " + name, targetid, False)])

        try:
            it = eval(expr,
                      railroad_diagrams.__dict__)
        except Exception as ex:
            print >>stderr, "@@eek!", self.content
            print >>stderr, "@@", ex
            raise

        diag = RailroadDiagram(railroad_diagrams.Diagram(it))

        if env.config.syntax_fp:
            out = env.config.syntax_fp
            dump({'name': name, 'expr': expr}, out)
            out.write(",\n\n")

        return [targetnode, ix, label, diag]

 def run(self):
     populated = CPPAutoDocObject._populate(self)
     indexnode = addnodes.index(entries=[])
     title = '{name} Namespace Reference'.format(name = self._get_name())
     main_section = self._make_main_section(title)
     if populated:
         obj = self._get_obj()
         section = self._make_section('Introduction')
         section += self._make_brief(obj)
         main_section += section
         section = self._make_section('Inner Definitions')
         main_section += section
         section += self._make_innernamespaces(obj)
         section += self._make_innermacros(obj)
         section += self._make_innertypes(obj)
         section += self._make_innerclasses(obj)
         section += self._make_innerfunctions(obj)
         section = self._make_section('Detailed Description')
         section += self._make_details(obj)
         main_section += section
         main_section += self._make_methods_documentation(obj)
         main_section += self._make_enums_documentation(obj)
     else:
         main_section += nodes.paragraph(text='Unknown Namespace.')
     return [indexnode, main_section]