def write(self, build_docnames, update_docnames, method='update'):
        # TODO: only rebuild updated?
        self.prepare_writing(build_docnames)

        def build_doc(docname):
            doctree = self.env.get_doctree(docname)
            doctree.settings = self.docsettings
            destination = io.StringOutput(encoding='utf-8')
            self.docwriter.write(doctree, destination)
            self.docwriter.assemble_parts()
            return self.docwriter.parts['fragment']

        def build_context(docname):
            body = build_doc(docname)
            filename = docname + self.app.config.source_suffix
            commit = get_git_commit(filename) 
            return os.path.basename(docname), dict(
                    body=body,
                    author=commit.author,
                    time=commit.author_time,
                    sha=commit.id,
                    filename=filename,
                    docname=docname)

        self.info('building comments...')
        context = dict(build_context(name) for name in build_docnames)
        self.info('doing stuff... ')

        # TODO: get docname from config
        outfilename = os.path.join(self.outdir, 'comments.json')
        osutil.ensuredir(os.path.dirname(outfilename))
        self.dump_context(context, outfilename)

    def visit(self, docname, image_node):
        rel_imagedir, abs_imagedir = get_imagedir(self.app, docname)
        basename = self.get_filename_for(image_node)
        if URI_PATTERN.match(image_node['uri']):
            srcpath = image_node['uri']
        else:
            srcpath = os.path.join(self.app.srcdir, image_node['uri'])
        abs_imgpath = os.path.join(abs_imagedir, basename)

        last_modified = self.get_last_modified_for(image_node)
        if last_modified is None:
            ret = False
        elif not os.path.exists(abs_imgpath) or os.stat(abs_imgpath).st_mtime < last_modified:
            ensuredir(os.path.dirname(abs_imgpath))
            ret = self.convert(image_node,
                               os.path.normpath(srcpath),
                               os.path.normpath(abs_imgpath))
        else:
            ret = True

        if ret:
            if last_modified is not None and os.path.exists(abs_imgpath):
                os.utime(abs_imgpath, (last_modified, last_modified))

            rel_imgpath = posixpath.join(rel_imagedir, basename)
            newnode = nodes.image(**image_node.attributes)
            newnode['candidates'] = {'*': rel_imgpath}
            newnode['uri'] = rel_imgpath
            image_node.replace_self(newnode)
        else:
            image_node.parent.remove(image_node)

 def install_lightbox_static_files(app):
     source_static_path = os.path.join(app.builder.srcdir, '_static')
     target_static_path = os.path.join(app.builder.outdir, '_static')
     source_lightbox_path = os.path.join(source_static_path, 'lightbox2')
     target_lightbox_path = os.path.join(target_static_path, 'lightbox2')
     relative_file_paths = []
     for root, _, file_names in os.walk(source_lightbox_path):
         for file_name in file_names:
             absolute_file_path = os.path.join(root, file_name)
             relative_file_path = os.path.relpath(
                 absolute_file_path,
                 source_static_path,
                 )
             relative_file_paths.append(relative_file_path)
     if os.path.exists(target_lightbox_path):
         shutil.rmtree(target_lightbox_path)
     for relative_file_path in app.builder.status_iterator(
         relative_file_paths,
         'installing lightbox files... ',
         brown,
         len(relative_file_paths),
         ):
         source_path = os.path.join(source_static_path, relative_file_path)
         target_path = os.path.join(target_static_path, relative_file_path)
         target_directory = os.path.dirname(target_path)
         if not os.path.exists(target_directory):
             ensuredir(target_directory)
         copyfile(source_path, target_path)
         if relative_file_path.endswith('.js'):
             app.add_javascript(relative_file_path)
         elif relative_file_path.endswith('.css'):
             app.add_stylesheet(relative_file_path)

    def render_to_file(self, file_name, template_name, context):
        """Render a template file to a file

        Ensures that target directories exist and only writes
        the file if the content has changed.

        Args:
          file_name: Target file name
          template_name: Name of template file
          context: dictionary to pass to jinja

        Returns:
          True if a file was written
        """
        content = self.render(template_name, {**self.extra_context, **context})

        # skip if exists and unchanged:
        if os.path.exists(file_name):
            with open(file_name, encoding="utf-8") as filedes:
                if filedes.read() == content:
                    return False  # unchanged

        ensuredir(op.dirname(file_name))
        with open(file_name, "w", encoding="utf-8") as filedes:
            filedes.write(content)
        return True

def install_backend_static_files(app, env):
    STATICS_DIR_PATH = os.path.join(app.builder.outdir, STATICS_DIR_NAME)
    dest_path = os.path.join(STATICS_DIR_PATH, 'sphinxcontrib-images',
                             app.sphinxcontrib_images_backend.__class__.__name__)
    files_to_copy = app.sphinxcontrib_images_backend.STATIC_FILES

    for source_file_path in app.builder.status_iterator(
        files_to_copy,
        'Copying static files for sphinxcontrib-images...',
        brown, len(files_to_copy)):

        dest_file_path = os.path.join(dest_path, source_file_path)

        if not os.path.exists(os.path.dirname(dest_file_path)):
            ensuredir(os.path.dirname(dest_file_path))

        source_file_path = os.path.join(os.path.dirname(
            sys.modules[app.sphinxcontrib_images_backend.__class__.__module__].__file__),
            source_file_path)

        copyfile(source_file_path, dest_file_path)

        if dest_file_path.endswith('.js'):
            app.add_javascript(os.path.relpath(dest_file_path, STATICS_DIR_PATH))
        elif dest_file_path.endswith('.css'):
            app.add_stylesheet(os.path.relpath(dest_file_path, STATICS_DIR_PATH))

def build_latex_doc(app, status, warning, engine, docclass):
    app.config.latex_engine = engine
    app.config.latex_documents[0] = app.config.latex_documents[0][:4] + (docclass,)

    LaTeXTranslator.ignore_missing_images = True
    app.builder.build_all()

    # file from latex_additional_files
    assert (app.outdir / 'svgimg.svg').isfile()

    # now, try to run latex over it
    with cd(app.outdir):
        try:
            ensuredir(engine)
            p = Popen([engine, '--interaction=nonstopmode',
                       '-output-directory=%s' % engine, 'SphinxTests.tex'],
                      stdout=PIPE, stderr=PIPE)
        except OSError:  # most likely the latex executable was not found
            raise SkipTest
        else:
            stdout, stderr = p.communicate()
            if p.returncode != 0:
                print(stdout)
                print(stderr)
                assert False, '%s exited with return code %s' % (
                    engine, p.returncode)

    def handle_page(self, pagename, ctx, templatename='page.html',
                    outfilename=None, event_arg=None):
        ctx['current_page_name'] = pagename
        self.add_sidebars(pagename, ctx)

        if not outfilename:
            outfilename = path.join(self.outdir,
                                    os_path(pagename) + self.out_suffix)

        self.app.emit('html-page-context', pagename, templatename,
                      ctx, event_arg)

        ensuredir(path.dirname(outfilename))
        f = open(outfilename, 'wb')
        try:
            self.implementation.dump(ctx, f, 2)
        finally:
            f.close()

        # if there is a source file, copy the source file for the
        # "show source" link
        if ctx.get('sourcename'):
            source_name = path.join(self.outdir, '_sources',
                                    os_path(ctx['sourcename']))
            ensuredir(path.dirname(source_name))
            copyfile(self.env.doc2path(pagename), source_name)

def _run_hg_command(command, override_dir=''):
    """
    Runs the given command, as if it were typed at the command line, in the
    appropriate directory.
    """
    verb = command[0]
    actions = hg_verbs[verb][1]
    try:
        command[0] = hg_verbs[verb][0]
        command.insert(0, executable)
        ensuredir(override_dir or local_repo_physical_dir)
        out = subprocess.Popen(command, stdout=subprocess.PIPE,
                               stderr=subprocess.PIPE,
                               cwd=override_dir or local_repo_physical_dir)
        if testing:
            # For some strange reason, unit tests fail if we don't have
            # a small pause here.
            import time
            time.sleep(0.1)

        stderr = out.stderr.readlines()
        if stderr:
            return stderr

        if out.returncode == 0 or out.returncode is None:
            if actions.get(0, '') == '<string>':
                return out.communicate()[0]
            else:
                return out.returncode
        else:
            return out.returncode

    except OSError as err:
        if err.strerror == 'No such file or directory':
            raise DVCSError('The ``hg`` executable file was not found.')

def copy_asset(source, destination, excluded=lambda path: False, context=None, renderer=None):
    """Copy asset files to destination recursively.

    On copying, it expands the template variables if context argument is given and
    the asset is a template file.

    :param source: The path to source file or directory
    :param destination: The path to destination directory
    :param excluded: The matcher to determine the given path should be copied or not
    :param context: The template variables.  If not given, template files are simply copied
    :param renderer: The template engine.  If not given, SphinxRenderer is used by default
    """
    if not os.path.exists(source):
        return

    ensuredir(destination)
    if os.path.isfile(source):
        copy_asset_file(source, destination, context, renderer)
        return

    for root, dirs, files in walk(source):
        reldir = relative_path(source, root)
        for dir in dirs[:]:
            if excluded(posixpath.join(reldir, dir)):
                dirs.remove(dir)
            else:
                ensuredir(posixpath.join(destination, reldir, dir))

        for filename in files:
            if not excluded(posixpath.join(reldir, filename)):
                copy_asset_file(posixpath.join(root, filename),
                                posixpath.join(destination, reldir),
                                context, renderer)

    def handle_page(self, pagename, ctx, templatename='page.html',
                    outfilename=None, event_arg=None):
        # type: (str, Dict, str, str, Any) -> None
        ctx['current_page_name'] = pagename
        self.add_sidebars(pagename, ctx)

        if not outfilename:
            outfilename = path.join(self.outdir,
                                    os_path(pagename) + self.out_suffix)

        # we're not taking the return value here, since no template is
        # actually rendered
        self.app.emit('html-page-context', pagename, templatename, ctx, event_arg)

        # make context object serializable
        for key in list(ctx):
            if isinstance(ctx[key], types.FunctionType):
                del ctx[key]

        ensuredir(path.dirname(outfilename))
        self.dump_context(ctx, outfilename)

        # if there is a source file, copy the source file for the
        # "show source" link
        if ctx.get('sourcename'):
            source_name = path.join(self.outdir, '_sources',
                                    os_path(ctx['sourcename']))
            ensuredir(path.dirname(source_name))
            copyfile(self.env.doc2path(pagename), source_name)

    def output_rst(self, root, source_suffix):
        if not self.objects:
            raise ExtensionError("No API objects exist. Can't continue")
        for id, obj in self.objects.items():

            if not obj or not obj.top_level_object:
                continue

            rst = obj.render()
            if not rst:
                continue

            detail_dir = os.path.join(root, obj.pathname)
            ensuredir(detail_dir)
            path = os.path.join(detail_dir, "%s%s" % ("index", source_suffix))
            with open(path, "wb") as detail_file:
                detail_file.write(rst.encode("utf-8"))

        # Render Top Index
        top_level_index = os.path.join(root, "index.rst")
        with open(top_level_index, "wb") as top_level_file:
            content = self.jinja_env.get_template("index.rst")
            top_level_file.write(
                content.render(pages=self.namespaces.values()).encode("utf-8")
            )

 def copy_image_files_pil(self):
     """Copy images using the PIL.
     The method tries to read and write the files with the PIL,
     converting the format and resizing the image if necessary/possible.
     """
     ensuredir(path.join(self.outdir, self.imagedir))
     for src in self.app.status_iterator(self.images, "copying images... ", brown, len(self.images)):
         dest = self.images[src]
         try:
             img = Image.open(path.join(self.srcdir, src))
         except IOError:
             if not self.is_vector_graphics(src):
                 self.warn("cannot read image file %r: copying it instead" % (path.join(self.srcdir, src),))
             try:
                 copyfile(path.join(self.srcdir, src), path.join(self.outdir, self.imagedir, dest))
             except (IOError, OSError) as err:
                 self.warn("cannot copy image file %r: %s" % (path.join(self.srcdir, src), err))
             continue
         if self.config.epub_fix_images:
             if img.mode in ("P",):
                 # See PIL documentation for Image.convert()
                 img = img.convert()
         if self.config.epub_max_image_width > 0:
             (width, height) = img.size
             nw = self.config.epub_max_image_width
             if width > nw:
                 nh = (height * nw) / width
                 img = img.resize((nw, nh), Image.BICUBIC)
         try:
             img.save(path.join(self.outdir, self.imagedir, dest))
         except (IOError, OSError) as err:
             self.warn("cannot write image file %r: %s" % (path.join(self.srcdir, src), err))

    def to_image(self, builder):
        if builder.format == 'html':
            reldir = "_images"
            outdir = os.path.join(builder.outdir, '_images')
        else:
            reldir = ""
            outdir = builder.outdir

        try:
            cacoo = Cacoo(builder.config.cacoo_apikey)
            last_modified = cacoo.get_last_modified(self['diagramid'])

            filename = "cacoo-%s.png" % self['diagramid'].replace('#', '-')
            path = os.path.join(outdir, filename)
            if not os.path.exists(path) or os.stat(path).st_mtime < last_modified:
                ensuredir(outdir)
                with open(path, 'wb') as fd:
                    fd.write(cacoo.get_image(self['diagramid']).read())
                os.utime(path, (last_modified, last_modified))
        except Exception as exc:
            builder.warn('Fail to download cacoo image: %s (check your cacoo_apikey or diagramid)' % exc)
            return nodes.Text('')

        relfn = os.path.join(reldir, filename)
        image_node = nodes.image(candidates={'*': relfn}, **self.attributes)
        image_node['uri'] = relfn

        return image_node

    def write_doc(self, docname, doctree):
        self.current_docname = docname
        destination = StringOutput(encoding='utf-8')
        self.writer.write(doctree, destination)
        outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix)
        ensuredir(path.dirname(outfilename))
        try:
            f = codecs.open(outfilename, 'w', 'utf-8')
            try:
		f.write("#rst2hooktail_source" + (linesep*2))
		for link in self.writer.links:
		  f.write(".. _%s: %s%s" % (link.children[0].astext(), link['refuri'], linesep))
                f.write(linesep)

                f.write(self.writer.output)
		f.write("@@author:%[email protected]@%s" % (self.config.copyright[6:], linesep))
		f.write("@@accept:%[email protected]@%s" % (ustrftime("%Y-%m-%d"), linesep))
		relations = self.env.collect_relations().get(docname)
		if relations and relations[0] and relations[0] != "index":
		  f.write("@@category:%[email protected]@%s" % (self.categories[relations[0]], linesep))
		f.write("@@id:%[email protected]@%s" % (docname.split('/')[-1], linesep))
            finally:
                f.close()
        except (IOError, OSError) as err:
            self.warn("error writing file %s: %s" % (outfilename, err))

    def output_rst(self, root, source_suffix):
        for id, obj in self.objects.items():

            if not obj or not obj.top_level_object:
                continue

            rst = obj.render()
            if not rst:
                continue

            try:
                filename = id.split('(')[0]
            except IndexError:
                filename = id
            filename = filename.replace('#', '-')
            detail_dir = os.path.join(root, *filename.split('.'))
            ensuredir(detail_dir)
            path = os.path.join(detail_dir, '%s%s' % ('index', source_suffix))
            with open(path, 'wb+') as detail_file:
                detail_file.write(rst.encode('utf-8'))

        # Render Top Index
        top_level_index = os.path.join(root, 'index.rst')
        pages = self.objects.values()
        with open(top_level_index, 'w+') as top_level_file:
            content = self.jinja_env.get_template('index.rst')
            top_level_file.write(content.render(pages=pages))

def get_image_filename(self, code, format, options, prefix='rackdiag'):
    """
    Get path of output file.
    """
    if format not in ('PNG', 'PDF'):
        raise RackdiagError('rackdiag error:\nunknown format: %s\n' % format)

    if format == 'PDF':
        try:
            import reportlab
        except ImportError:
            msg = 'rackdiag error:\n' + \
                  'colud not output PDF format; Install reportlab\n'
            raise RackdiagError(msg)

    hashkey = code.encode('utf-8') + str(options)
    fname = '%s-%s.%s' % (prefix, sha(hashkey).hexdigest(), format.lower())
    if hasattr(self.builder, 'imgpath'):
        # HTML
        relfn = posixpath.join(self.builder.imgpath, fname)
        outfn = os.path.join(self.builder.outdir, '_images', fname)
    else:
        # LaTeX
        relfn = fname
        outfn = os.path.join(self.builder.outdir, fname)

    if os.path.isfile(outfn):
        return relfn, outfn

    ensuredir(os.path.dirname(outfn))

    return relfn, outfn

 def init_indexing(self, changed=[]):
     ensuredir(self.db_path)
     self.database = xapian.WritableDatabase(self.db_path,
                                             xapian.DB_CREATE_OR_OPEN)
     self.indexer = xapian.TermGenerator()
     stemmer = xapian.Stem("english")
     self.indexer.set_stemmer(stemmer)

    def copy_static_files(self):
        # copy static files
        self.info(bold('copying static files... '), nonl=True)
        ensuredir(path.join(self.outdir, '_static'))
        # first, create pygments style file
        f = open(path.join(self.outdir, '_static', 'pygments.css'), 'w')
        f.write(self.highlighter.get_stylesheet())
        f.close()
        # then, copy translations JavaScript file
        if self.config.language is not None:
            jsfile = self._get_translations_js()
            if jsfile:
                copyfile(jsfile, path.join(self.outdir, '_static',
                                           'translations.js'))

        # copy non-minified stemmer JavaScript file
        if self.indexer is not None:
            jsfile = self.indexer.get_js_stemmer_rawcode()
            if jsfile:
                copyfile(jsfile, path.join(self.outdir, '_static', '_stemmer.js'))

        ctx = self.globalcontext.copy()

        # add context items for search function used in searchtools.js_t
        if self.indexer is not None:
            ctx.update(self.indexer.context_for_searchtool())

        # then, copy over theme-supplied static files
        if self.theme:
            for theme_path in self.theme.get_dirchain()[::-1]:
                entry = path.join(theme_path, 'static')
                copy_asset(entry, path.join(self.outdir, '_static'), excluded=DOTFILES,
                           context=ctx, renderer=self.templates)
        # then, copy over all user-supplied static files
        excluded = Matcher(self.config.exclude_patterns + ["**/.*"])
        for static_path in self.config.html_static_path:
            entry = path.join(self.confdir, static_path)
            if not path.exists(entry):
                self.warn('html_static_path entry %r does not exist' % entry)
                continue
            copy_asset(entry, path.join(self.outdir, '_static'), excluded,
                       context=ctx, renderer=self.templates)
        # copy logo and favicon files if not already in static path
        if self.config.html_logo:
            logobase = path.basename(self.config.html_logo)
            logotarget = path.join(self.outdir, '_static', logobase)
            if not path.isfile(path.join(self.confdir, self.config.html_logo)):
                self.warn('logo file %r does not exist' % self.config.html_logo)
            elif not path.isfile(logotarget):
                copyfile(path.join(self.confdir, self.config.html_logo),
                         logotarget)
        if self.config.html_favicon:
            iconbase = path.basename(self.config.html_favicon)
            icontarget = path.join(self.outdir, '_static', iconbase)
            if not path.isfile(path.join(self.confdir, self.config.html_favicon)):
                self.warn('favicon file %r does not exist' % self.config.html_favicon)
            elif not path.isfile(icontarget):
                copyfile(path.join(self.confdir, self.config.html_favicon),
                         icontarget)
        self.info('done')

 def __init__(self, db_path):
     ensuredir(db_path)
     if index.exists_in(db_path):
         self.index = index.open_dir(db_path)
     else:
         self.index = index.create_in(db_path, schema=self.schema)
     self.qparser = QueryParser('text', self.schema)

def copy_static_entry(source, targetdir, builder, context={},
                      exclude_matchers=(), level=0):
    # type: (str, str, Any, Dict, Tuple[Callable, ...], int) -> None
    """[DEPRECATED] Copy a HTML builder static_path entry from source to targetdir.

    Handles all possible cases of files, directories and subdirectories.
    """
    warnings.warn('sphinx.util.copy_static_entry is deprecated for removal',
                  RemovedInSphinx30Warning, stacklevel=2)

    if exclude_matchers:
        relpath = relative_path(path.join(builder.srcdir, 'dummy'), source)
        for matcher in exclude_matchers:
            if matcher(relpath):
                return
    if path.isfile(source):
        copy_asset_file(source, targetdir, context, builder.templates)
    elif path.isdir(source):
        ensuredir(targetdir)
        for entry in os.listdir(source):
            if entry.startswith('.'):
                continue
            newtarget = targetdir
            if path.isdir(path.join(source, entry)):
                newtarget = path.join(targetdir, entry)
            copy_static_entry(path.join(source, entry), newtarget,
                              builder, context, level=level + 1,
                              exclude_matchers=exclude_matchers)