def write(self, *ignored):
        if self.config.man_pages:
            # build manpages from config.man_pages as usual
            ManualPageBuilder.write(self, *ignored)

        self.info(bold("scan master tree for kernel-doc man-pages ... ") + darkgreen("{"), nonl=True)

        master_tree = self.env.get_doctree(self.config.master_doc)
        master_tree = inline_all_toctrees(
            self, set(), self.config.master_doc, master_tree, darkgreen, [self.config.master_doc])
        self.info(darkgreen("}"))
        man_nodes   = master_tree.traverse(condition=self.is_manpage)
        if not man_nodes and not self.config.man_pages:
            self.warn('no "man_pages" config value nor manual section found; no manual pages '
                      'will be written')
            return

        self.info(bold('writing man pages ... '), nonl=True)

        for man_parent in man_nodes:

            doc_tree = self.get_partial_document(man_parent)
            Section2Manpage(doc_tree).apply()

            if not doc_tree.man_info["authors"] and self.config.author:
                doc_tree.man_info["authors"].append(self.config.author)

            doc_writer   = ManualPageWriter(self)
            doc_settings = OptionParser(
                defaults            = self.env.settings
                , components        = (doc_writer,)
                , read_config_files = True
                , ).get_default_values()

            doc_settings.__dict__.update(doc_tree.man_info)
            doc_tree.settings = doc_settings
            targetname  = '%s.%s' % (doc_tree.man_info.title, doc_tree.man_info.section)
            if doc_tree.man_info.decl_type in [
                    "struct", "enum", "union", "typedef"]:
                targetname = "%s_%s" % (doc_tree.man_info.decl_type, targetname)

            destination = FileOutput(
                destination_path = path.join(self.outdir, targetname)
                , encoding='utf-8')

            self.info(darkgreen(targetname) + " ", nonl=True)
            self.env.resolve_references(doc_tree, doc_tree.man_info.manpage, self)

            # remove pending_xref nodes
            for pendingnode in doc_tree.traverse(addnodes.pending_xref):
                pendingnode.replace_self(pendingnode.children)
            doc_writer.write(doc_tree, destination)
        self.info()

    def finish(self):
        I18nBuilder.finish(self)
        data = dict(
            version = self.config.version,
            copyright = self.config.copyright,
            project = self.config.project,
            # XXX should supply tz
            ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z'),
        )
        self._create_project_folder()
        for section, messages in self.status_iterator(
                self.catalogs.iteritems(), "writing message catalogs... ",
                lambda (section, _):darkgreen(section), len(self.catalogs)):

            pofn = path.join(self.config.omegat_project_path,
                             "source", section + '.po')
            pofile = open(pofn, 'w', encoding='utf-8')
            try:
                pofile.write(POHEADER % data)
                for message, positions in messages.iteritems():
                    # message contains *one* line of text ready for translation
                    position = ", ".join(["%s(%s)" % (source, line) 
                                              for (source, line) in positions])
                    message = message.replace(u'\\', ur'\\'). \
                                      replace(u'"', ur'\"')
                    pomsg = u'#%s\nmsgid "%s"\nmsgstr ""\n\n' % (position, message)
                    pofile.write(pomsg)
            finally:
                pofile.close()

    def find_files(self, patterns, dirs, ignore):
        # pylint: disable=too-many-nested-blocks
        if not ignore:
            ignore = []
        files_to_read = []
        for _dir in dirs:
            for root, dirnames, filenames in os.walk(_dir):
                for pattern in patterns:
                    for filename in fnmatch.filter(filenames, pattern):
                        skip = False

                        # Skip ignored files
                        for ignore_pattern in ignore:
                            if fnmatch.fnmatch(os.path.join(root, filename), ignore_pattern):
                                self.app.info(
                                    bold('[AutoAPI] ') +
                                    darkgreen("Ignoring %s/%s" % (root, filename))
                                )
                                skip = True

                        if skip:
                            continue
                        # Make sure the path is full
                        if os.path.isabs(filename):
                            files_to_read.append(filename)
                        else:
                            files_to_read.append(os.path.join(root, filename))

        for _path in self.app.status_iterator(
                files_to_read,
                '[AutoAPI] Reading files... ',
                darkgreen,
                len(files_to_read)):
            yield _path

def doctree_read(app, doctree):
    """
    Inject AutoAPI into the TOC Tree dynamically.
    """
    if app.env.docname == "index":
        all_docs = set()
        insert = True
        nodes = doctree.traverse(toctree)
        toc_entry = "%s/index" % app.config.autoapi_root
        add_entry = (
            nodes
            and app.config.autoapi_generate_api_docs
            and app.config.autoapi_add_toctree_entry
        )
        if not add_entry:
            return
        # Capture all existing toctree entries
        for node in nodes:
            for entry in node["entries"]:
                all_docs.add(entry[1])
        # Don't insert autoapi it's already present
        for doc in all_docs:
            if doc.find(app.config.autoapi_root) != -1:
                insert = False
        if insert and app.config.autoapi_add_toctree_entry:
            # Insert AutoAPI index
            nodes[-1]["entries"].append((None, u"%s/index" % app.config.autoapi_root))
            nodes[-1]["includefiles"].append(u"%s/index" % app.config.autoapi_root)
            message_prefix = bold("[AutoAPI] ")
            message = darkgreen(
                "Adding AutoAPI TOCTree [{0}] to index.rst".format(toc_entry)
            )
            LOGGER.info(message_prefix + message)

 def assemble_doctree(self, indexfile):
     docnames = set([indexfile])
     self.info(darkgreen(indexfile) + " ", nonl=1)
     tree = self.env.get_doctree(indexfile)
     tree['docname'] = indexfile
     # extract toctree nodes from the tree and put them in a fresh document
     new_tree = docutils.utils.new_document('<rinoh output>')
     for node in tree.traverse(addnodes.toctree):
         new_tree += node
     largetree = inline_all_toctrees(self, docnames, indexfile, new_tree,
                                     darkgreen)
     largetree['docname'] = indexfile
     self.info()
     self.info("resolving references...")
     self.env.resolve_references(largetree, indexfile, self)
     # resolve :ref:s to distant tex files -- we can't add a cross-reference,
     # but append the document name
     for pendingnode in largetree.traverse(addnodes.pending_xref):
         docname = pendingnode['refdocname']
         sectname = pendingnode['refsectname']
         newnodes = [nodes.emphasis(sectname, sectname)]
         for subdir, title in self.titles:
             if docname.startswith(subdir):
                 newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
                 newnodes.append(nodes.emphasis(title, title))
                 newnodes.append(nodes.Text(')', ')'))
                 break
         else:
             pass
         pendingnode.replace_self(newnodes)
     return largetree

 def process_result(self, result):
     uri, docname, lineno, status, info, code = result
     if status == 'unchecked':
         return
     if status == 'working' and info != 'new':
         return
     if lineno:
         self.info('(line %4d) ' % lineno, nonl=1)
     if status == 'ignored':
         self.info(darkgray('-ignored- ') + uri)
     elif status == 'local':
         self.info(darkgray('-local-   ') + uri)
         self.write_entry('local', docname, lineno, uri)
     elif status == 'working':
         self.info(darkgreen('ok        ')  + uri)
     elif status == 'broken':
         self.info(red('broken    ') + uri + red(' - ' + info))
         self.write_entry('broken', docname, lineno, uri + ': ' + info)
         if self.app.quiet:
             self.warn('broken link: %s' % uri,
                       '%s:%s' % (self.env.doc2path(docname), lineno))
     elif status == 'redirected':
         text, color = {
             301: ('permanently', darkred),
             302: ('with Found', purple),
             303: ('with See Other', purple),
             307: ('temporarily', turquoise),
             0:   ('with unknown code', purple),
         }[code]
         self.write_entry('redirected ' + text, docname, lineno,
                          uri + ' to ' + info)
         self.info(color('redirect  ') + uri + color(' - ' + text + ' to '  + info))

    def check(self, node, docname):
        uri = node['refuri']

        if '#' in uri:
            uri = uri.split('#')[0]

        if uri in self.good:
            return

        lineno = None
        while lineno is None:
            node = node.parent
            if node is None:
                break
            lineno = node.line

        if len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:':
            return

        if lineno:
            self.info('(line %3d) ' % lineno, nonl=1)
        for rex in self.to_ignore:
            if rex.match(uri):
                self.info(uri + ' - ' + darkgray('ignored'))
                return
        if uri[0:5] == 'http:' or uri[0:6] == 'https:':
            self.info(uri, nonl=1)

            if uri in self.broken:
                (r, s) = self.broken[uri]
            elif uri in self.redirected:
                (r, s) = self.redirected[uri]
            else:
                (r, s) = self.resolve(uri)

            if r == 0:
                self.info(' - ' + darkgreen('working'))
                self.good.add(uri)
            elif r == 2:
                self.info(' - ' + red('broken: ') + s)
                self.write_entry('broken', docname, lineno, uri + ': ' + s)
                self.broken[uri] = (r, s)
                if self.app.quiet:
                    self.warn('broken link: %s' % uri,
                              '%s:%s' % (self.env.doc2path(docname), lineno))
            else:
                self.info(' - ' + purple('redirected') + ' to ' + s)
                self.write_entry('redirected', docname,
                                 lineno, uri + ' to ' + s)
                self.redirected[uri] = (r, s)
        else:
            self.info(uri + ' - ' + darkgray('local'))
            self.write_entry('local', docname, lineno, uri)

        if self.broken:
            self.app.statuscode = 1

def build_finished(app, exception):
    if not app.config.autoapi_keep_files:
        normalized_root = os.path.normpath(os.path.join(app.confdir, app.config.autoapi_root))
        if app.verbosity > 1:
            app.info(bold('[AutoAPI] ') + darkgreen('Cleaning generated .rst files'))
        shutil.rmtree(normalized_root)

        mapper = default_backend_mapping[app.config.autoapi_type]
        if hasattr(mapper, 'build_finished'):
            mapper.build_finished(app, exception)

def build_finished(app, exception):
    if not app.config.autoapi_keep_files and app.config.autoapi_generate_api_docs:
        normalized_root = os.path.normpath(
            os.path.join(app.confdir, app.config.autoapi_root)
        )
        if app.verbosity > 1:
            LOGGER.info(bold("[AutoAPI] ") + darkgreen("Cleaning generated .rst files"))
        shutil.rmtree(normalized_root)

        sphinx_mapper = default_backend_mapping[app.config.autoapi_type]
        if hasattr(sphinx_mapper, "build_finished"):
            sphinx_mapper.build_finished(app, exception)

    def assemble_doctree(self, indexfile, toctree_only, appendices):
        self.docnames = set([indexfile] + appendices)
        self.info(darkgreen(indexfile) + " ", nonl=1)
        tree = self.env.get_doctree(indexfile)
        tree['docname'] = indexfile
        if toctree_only:
            # extract toctree nodes from the tree and put them in a
            # fresh document
            new_tree = new_document('<latex output>')
            new_sect = nodes.section()
            new_sect += nodes.title(u'<Set title in conf.py>',
                                    u'<Set title in conf.py>')
            new_tree += new_sect
            for node in tree.traverse(addnodes.toctree):
                new_sect += node
            tree = new_tree
        largetree = inline_all_toctrees(self, self.docnames, indexfile, tree,
                                        darkgreen)
        largetree['docname'] = indexfile
        for docname in appendices:
            appendix = self.env.get_doctree(docname)
            appendix['docname'] = docname
            largetree.append(appendix)
        self.info()
        self.info("resolving references...")
        #for node in largetree.traverse(nodes.target):
        #    print node

        self.env.resolve_references(largetree, indexfile, self)
        # resolve :ref:s to distant tex files -- we can't add a cross-reference,
        # but append the document name
        for pendingnode in largetree.traverse(addnodes.pending_xref):
            docname = pendingnode['refdocname']
            sectname = pendingnode['refsectname']
            newnodes = [nodes.emphasis(sectname, sectname)]
            for subdir, title in self.titles:
                if docname.startswith(subdir):
                    newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
                    newnodes.append(nodes.emphasis(title, title))
                    newnodes.append(nodes.Text(')', ')'))
                    break
            else:
                pass
            pendingnode.replace_self(newnodes)

#        for node in largetree.traverse(nodes.reference):
#            print node


        return largetree

    def check(self, node, docname):
        uri = node["refuri"]

        if "#" in uri:
            uri = uri.split("#")[0]

        if uri in self.good:
            return

        lineno = None
        while lineno is None:
            node = node.parent
            if node is None:
                break
            lineno = node.line

        if len(uri) == 0 or uri[0:7] == "mailto:" or uri[0:4] == "ftp:":
            return

        if lineno:
            self.info("(line %3d) " % lineno, nonl=1)
        if uri[0:5] == "http:" or uri[0:6] == "https:":
            self.info(uri, nonl=1)

            if uri in self.broken:
                (r, s) = self.broken[uri]
            elif uri in self.redirected:
                (r, s) = self.redirected[uri]
            else:
                (r, s) = self.resolve(uri)

            if r == 0:
                self.info(" - " + darkgreen("working"))
                self.good.add(uri)
            elif r == 2:
                self.info(" - " + red("broken: ") + s)
                self.write_entry("broken", docname, lineno, uri + ": " + s)
                self.broken[uri] = (r, s)
                if self.app.quiet:
                    self.warn("broken link: %s" % uri, "%s:%s" % (self.env.doc2path(docname), lineno))
            else:
                self.info(" - " + purple("redirected") + " to " + s)
                self.write_entry("redirected", docname, lineno, uri + " to " + s)
                self.redirected[uri] = (r, s)
        else:
            self.info(uri + " - " + darkgray("local"))
            self.write_entry("local", docname, lineno, uri)

        if self.broken:
            self.app.statuscode = 1

    def check(self, node, docname):
        uri = node['refuri']

        if '#' in uri:
            uri = uri.split('#')[0]

        if uri in self.good:
            return

        lineno = None
        while lineno is None and node:
            node = node.parent
            lineno = node.line

        if uri[0:5] == 'http:' or uri[0:6] == 'https:':
            self.info(uri, nonl=1)

            if uri in self.broken:
                (r, s) = self.broken[uri]
            elif uri in self.redirected:
                (r, s) = self.redirected[uri]
            else:
                (r, s) = self.resolve(uri)

            if r == 0:
                self.info(' - ' + darkgreen('working'))
                self.good.add(uri)
            elif r == 2:
                self.info(' - ' + red('broken: ') + s)
                self.write_entry('broken', docname, lineno, uri + ': ' + s)
                self.broken[uri] = (r, s)
                if self.app.quiet:
                    self.warn('%s:%s: broken link: %s' % (docname, lineno, uri))
            else:
                self.info(' - ' + purple('redirected') + ' to ' + s)
                self.write_entry('redirected', docname, lineno, uri + ' to ' + s)
                self.redirected[uri] = (r, s)
        elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:':
            return
        else:
            self.warn(uri + ' - ' + red('malformed!'))
            self.write_entry('malformed', docname, lineno, uri)
            if self.app.quiet:
                self.warn('%s:%s: malformed link: %s' % (docname, lineno, uri))
            self.app.statuscode = 1

        if self.broken:
            self.app.statuscode = 1

    def write_doc(self, docname, doctree):
        self.checker.push_filters(self.env.spelling_document_filters[docname])

        for node in doctree.traverse(docutils.nodes.Text):
            if (node.tagname == '#text'
                    and node.parent
                    and node.parent.tagname in self.TEXT_NODES):

                # Figure out the line number for this node by climbing the
                # tree until we find a node that has a line number.
                lineno = None
                parent = node
                seen = set()
                while lineno is None:
                    #self.info('looking for line number on %r' % node)
                    seen.add(parent)
                    parent = node.parent
                    if parent is None or parent in seen:
                        break
                    lineno = parent.line

                # Check the text of the node.
                for word, suggestions in self.checker.check(node.astext()):
                    msg_parts = [docname + '.po']
                    if lineno:
                        msg_parts.append(darkgreen(str(lineno)))
                    msg_parts.append(' %s ' % red(word))
                    msg_parts.append(self.format_suggestions(suggestions))
                    msg_parts.append(node.astext())
                    msg = ':'.join(msg_parts)
                    self.info(msg)

                    if False:  # To generate simple output.txt for spell_statistic command
                        self.output.write('%s\n' % word)
                    else:
                        self.output.write(u"%s:%s: (%s) %s | %s\n" % (
                            docname + '.po',
                            lineno, word,
                            self.format_suggestions(suggestions),
                            node.astext()
                        ))

                    # We found at least one bad spelling, so set the status
                    # code for the app to a value that indicates an error.
                    self.app.statuscode = 1

        self.checker.pop_filters()
        return

    def write(self, *ignored):
        # type: (Any) -> None
        docwriter = ManualPageWriter(self)
        docsettings = OptionParser(
            defaults=self.env.settings,
            components=(docwriter,),
            read_config_files=True).get_default_values()  # type: Any

        logger.info(bold(__('writing... ')), nonl=True)

        for info in self.config.man_pages:
            docname, name, description, authors, section = info
            if docname not in self.env.all_docs:
                logger.warning(__('"man_pages" config value references unknown '
                                  'document %s'), docname)
                continue
            if isinstance(authors, str):
                if authors:
                    authors = [authors]
                else:
                    authors = []

            docsettings.title = name
            docsettings.subtitle = description
            docsettings.authors = authors
            docsettings.section = section

            targetname = '%s.%s' % (name, section)
            logger.info(darkgreen(targetname) + ' { ', nonl=True)
            destination = FileOutput(
                destination_path=path.join(self.outdir, targetname),
                encoding='utf-8')

            tree = self.env.get_doctree(docname)
            docnames = set()  # type: Set[str]
            largetree = inline_all_toctrees(self, docnames, docname, tree,
                                            darkgreen, [docname])
            largetree.settings = docsettings
            logger.info('} ', nonl=True)
            self.env.resolve_references(largetree, docname, self)
            # remove pending_xref nodes
            for pendingnode in largetree.traverse(addnodes.pending_xref):
                pendingnode.replace_self(pendingnode.children)

            docwriter.write(largetree, destination)
        logger.info('')

    def run(self):
        if self.has_run:
            return

        App.builder.info("running test %s ..." % darkgreen(self.path))

        self.rst_output = os.path.join(BTestTmp, "%s" % self.tag)
        os.environ["BTEST_RST_OUTPUT"] = self.rst_output

        self.cleanTmps()

        try:
            subprocess.check_call("btest -S %s" % self.path, shell=True)
        except (OSError, IOError, subprocess.CalledProcessError) as e:
            # Equivalent to Directive.error(); we don't have an
            # directive object here and can't pass it in because
            # it doesn't pickle.
            App.builder.warn(red("BTest error: %s" % e))

def doctree_read(app, doctree):
    all_docs = set()
    insert = True
    if app.env.docname == 'index':
        nodes = doctree.traverse(toctree)
        if not nodes:
            return
        for node in nodes:
            for entry in node['entries']:
                all_docs.add(entry[1])
        for doc in all_docs:
            if doc.find(app.config.autoapi_root) != -1:
                insert = False
        if insert and app.config.autoapi_add_toctree_entry:
            nodes[-1]['entries'].append(
                (None, u'%s/index' % app.config.autoapi_root)
            )
            nodes[-1]['includefiles'].append(u'%s/index' % app.config.autoapi_root)
            app.info(bold('[AutoAPI] ') + darkgreen('Adding AutoAPI TOCTree to index.rst'))

 def assemble_doctree(self, indexfile, toctree_only, appendices):
     # type: (unicode, bool, List[unicode]) -> nodes.Node
     self.docnames = set([indexfile] + appendices)
     logger.info(darkgreen(indexfile) + " ", nonl=1)
     tree = self.env.get_doctree(indexfile)
     tree['docname'] = indexfile
     if toctree_only:
         # extract toctree nodes from the tree and put them in a
         # fresh document
         new_tree = new_document('<texinfo output>')
         new_sect = nodes.section()
         new_sect += nodes.title(u'<Set title in conf.py>',
                                 u'<Set title in conf.py>')
         new_tree += new_sect
         for node in tree.traverse(addnodes.toctree):
             new_sect += node
         tree = new_tree
     largetree = inline_all_toctrees(self, self.docnames, indexfile, tree,
                                     darkgreen, [indexfile])
     largetree['docname'] = indexfile
     for docname in appendices:
         appendix = self.env.get_doctree(docname)
         appendix['docname'] = docname
         largetree.append(appendix)
     logger.info('')
     logger.info("resolving references...")
     self.env.resolve_references(largetree, indexfile, self)
     # TODO: add support for external :ref:s
     for pendingnode in largetree.traverse(addnodes.pending_xref):
         docname = pendingnode['refdocname']
         sectname = pendingnode['refsectname']
         newnodes = [nodes.emphasis(sectname, sectname)]
         for subdir, title in self.titles:
             if docname.startswith(subdir):
                 newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
                 newnodes.append(nodes.emphasis(title, title))
                 newnodes.append(nodes.Text(')', ')'))
                 break
         else:
             pass
         pendingnode.replace_self(newnodes)
     return largetree

    def write(self, *ignored):
        # overwritten -- use our own version of the Writer
        docwriter = CyrusManualPageWriter(self)
        docsettings = OptionParser(
            defaults=self.env.settings,
            components=(docwriter,),
            read_config_files=True).get_default_values()

        self.info(bold('writing... '), nonl=True)

        for info in self.config.man_pages:
            docname, name, description, authors, section = info
            if isinstance(authors, basestring):
                if authors:
                    authors = [authors]
                else:
                    authors = []

            targetname = '%s.%s' % (name, section)
            self.info(darkgreen(targetname) + ' { ', nonl=True)
            destination = FileOutput(
                destination_path=path.join(self.outdir, targetname),
                encoding='utf-8')

            tree = self.env.get_doctree(docname)
            docnames = set()
            largetree = inline_all_toctrees(self, docnames, docname, tree,
                                            darkgreen)
            self.info('} ', nonl=True)
            self.env.resolve_references(largetree, docname, self)
            # remove pending_xref nodes
            for pendingnode in largetree.traverse(addnodes.pending_xref):
                pendingnode.replace_self(pendingnode.children)

            largetree.settings = docsettings
            largetree.settings.title = name
            largetree.settings.subtitle = description
            largetree.settings.authors = authors
            largetree.settings.section = section

            docwriter.write(largetree, destination)
        self.info()

    def run(self):
        self.assert_has_content()

        env = self.state.document.settings.env
        btest_base = env.config.btest_base
        btest_tests = env.config.btest_tests

        tag = self.arguments[0]

        if not btest_base:
            return self.error("error: btest_base not set in config")

        if not btest_tests:
            return self.error("error: btest_tests not set in config")

        if not os.path.exists(btest_base):
            return self.error("error: btest_base directory '%s' does not exists" % btest_base)

        if not os.path.exists(os.path.join(btest_base, btest_tests)):
            return self.error("error: btest_tests directory '%s' does not exists" % os.path.join(btest_base, btest_tests))

        os.chdir(btest_base)

        tmp = tempfile.mktemp(prefix="rst-btest")
        file = os.path.join(btest_tests, tag + ".btest")

        self.message("running test %s ..." % darkgreen(file))

        # Save the test.
        out = open(file, "w")
        for line in self.content:
            print >>out, line

        out.close()

        # Run it.
        os.environ["BTEST_RST_OUTPUT"] = tmp

        try:
            subprocess.check_call("btest -qd %s" % file, shell=True)
        except (OSError, IOError, subprocess.CalledProcessError), e:
            return self.error("btest: %s" % e)

 def process_tree(docname, tree):
     tree = tree.deepcopy()
     for toctreenode in tree.traverse(addnodes.toctree):
         newnodes = []
         includefiles = map(str, toctreenode['includefiles'])
         for includefile in includefiles:
             try:
                 self.info(darkgreen(includefile) + " ", nonl=1)
                 subtree = process_tree(includefile,
                 self.env.get_doctree(includefile))
                 self.docnames.add(includefile)
             except Exception:
                 self.warn('%s: toctree contains ref to nonexisting file %r'\
                                              % (docname, includefile))
             else:
                 sof = addnodes.start_of_file(docname=includefile)
                 sof.children = subtree.children
                 newnodes.append(sof)
         toctreenode.parent.replace(toctreenode, newnodes)
     return tree