def build_navigation_doc(self, outdir=None, outname='nav.xhtml'):
        # type: (str, str) -> None
        """Write the metainfo file nav.xhtml."""
        if outdir:
            warnings.warn('The arguments of Epub3Builder.build_navigation_doc() '
                          'is deprecated.', RemovedInSphinx40Warning, stacklevel=2)
        else:
            outdir = self.outdir

        logger.info(__('writing %s file...'), outname)

        if self.config.epub_tocscope == 'default':
            doctree = self.env.get_and_resolve_doctree(
                self.config.master_doc, self,
                prune_toctrees=False, includehidden=False)
            refnodes = self.get_refnodes(doctree, [])
            self.toc_add_files(refnodes)
        else:
            # 'includehidden'
            refnodes = self.refnodes
        navlist = self.build_navlist(refnodes)
        copy_asset_file(path.join(self.template_dir, 'nav.xhtml_t'),
                        path.join(outdir, outname),
                        self.navigation_doc_metadata(navlist))

        # Add nav.xhtml to epub file
        if outname not in self.files:
            self.files.append(outname)

def copy_static_entry(source, targetdir, builder, context={},
                      exclude_matchers=(), level=0):
    # type: (unicode, unicode, 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):
        if not path.isdir(targetdir):
            os.mkdir(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)

    def build_toc(self, outdir=None, outname='toc.ncx'):
        # type: (str, str) -> None
        """Write the metainfo file toc.ncx."""
        if outdir:
            warnings.warn('The arguments of EpubBuilder.build_toc() is deprecated.',
                          RemovedInSphinx40Warning, stacklevel=2)
        else:
            outdir = self.outdir

        logger.info(__('writing %s file...'), outname)

        if self.config.epub_tocscope == 'default':
            doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
                                                       self, prune_toctrees=False,
                                                       includehidden=False)
            refnodes = self.get_refnodes(doctree, [])
            self.toc_add_files(refnodes)
        else:
            # 'includehidden'
            refnodes = self.refnodes
        self.check_refnodes(refnodes)
        navpoints = self.build_navpoints(refnodes)
        level = max(item['level'] for item in self.refnodes)
        level = min(level, self.config.epub_tocdepth)
        copy_asset_file(path.join(self.template_dir, 'toc.ncx_t'),
                        path.join(outdir, outname),
                        self.toc_metadata(level, navpoints))

def copy_static_entry(source, targetdir, builder, context={},
                      exclude_matchers=(), level=0):
    """[DEPRECATED] Copy a HTML builder static_path entry from source to targetdir.

    Handles all possible cases of files, directories and subdirectories.
    """
    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):
        if not path.isdir(targetdir):
            os.mkdir(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)

 def build_container(self, outdir, outname):
     # type: (unicode, unicode) -> None
     """Write the metainfo file META-INF/container.xml."""
     logger.info('writing %s file...', outname)
     filename = path.join(outdir, outname)
     ensuredir(path.dirname(filename))
     copy_asset_file(path.join(self.template_dir, 'container.xml'), filename)

 def build_access_page(self, language_dir: str) -> None:
     """Build the access page."""
     context = {
         'toc': self.config.master_doc + self.out_suffix,
         'title': self.config.applehelp_title,
     }
     copy_asset_file(path.join(template_dir, '_access.html_t'), language_dir, context)

 def copy_support_files(self):
     # type: () -> None
     try:
         with progress_message(__('copying Texinfo support files')):
             logger.info('Makefile ', nonl=True)
             copy_asset_file(os.path.join(template_dir, 'Makefile'), self.outdir)
     except OSError as err:
         logger.warning(__("error writing file Makefile: %s"), err)

    def copy_applehelp_icon(self, resources_dir: str) -> None:
        """Copy the icon, if one is supplied."""
        if self.config.applehelp_icon:

            try:
                with progress_message(__('copying icon... ')):
                    applehelp_icon = path.join(self.srcdir, self.config.applehelp_icon)
                    copy_asset_file(applehelp_icon, resources_dir)
            except Exception as err:
                logger.warning(__('cannot copy icon file %r: %s'), applehelp_icon, err)

    def build_mimetype(self, outdir=None, outname='mimetype'):
        # type: (str, str) -> None
        """Write the metainfo file mimetype."""
        if outdir:
            warnings.warn('The arguments of EpubBuilder.build_mimetype() is deprecated.',
                          RemovedInSphinx40Warning, stacklevel=2)
        else:
            outdir = self.outdir

        logger.info(__('writing %s file...'), outname)
        copy_asset_file(path.join(self.template_dir, 'mimetype'),
                        path.join(outdir, outname))

    def build_container(self, outdir=None, outname='META-INF/container.xml'):
        # type: (str, str) -> None
        """Write the metainfo file META-INF/container.xml."""
        if outdir:
            warnings.warn('The arguments of EpubBuilder.build_container() is deprecated.',
                          RemovedInSphinx40Warning, stacklevel=2)
        else:
            outdir = self.outdir

        logger.info(__('writing %s file...'), outname)
        filename = path.join(outdir, outname)
        ensuredir(path.dirname(filename))
        copy_asset_file(path.join(self.template_dir, 'container.xml'), filename)

    def finish(self):
        # type: () -> None
        self.copy_image_files()

        logger.info(bold(__('copying Texinfo support files... ')), nonl=True)
        # copy Makefile
        fn = path.join(self.outdir, 'Makefile')
        logger.info(fn, nonl=1)
        try:
            copy_asset_file(os.path.join(template_dir, 'Makefile'), fn)
        except (IOError, OSError) as err:
            logger.warning(__("error writing file %s: %s"), fn, err)
        logger.info(__(' done'))

    def copy_stopword_list(self) -> None:
        """Copy a stopword list (.stp) to outdir.

        The stopword list contains a list of words the full text search facility
        shouldn't index.  Note that this list must be pretty small.  Different
        versions of the MS docs claim the file has a maximum size of 256 or 512
        bytes (including \r\n at the end of each line).  Note that "and", "or",
        "not" and "near" are operators in the search language, so no point
        indexing them even if we wanted to.
        """
        template = path.join(template_dir, 'project.stp')
        filename = path.join(self.outdir, self.config.htmlhelp_basename + '.stp')
        copy_asset_file(template, filename)

    def finish(self):
        # copy image files
        if self.images:
            self.info(bold('copying images...'), nonl=1)
            for src, dest in iteritems(self.images):
                self.info(' '+src, nonl=1)
                copy_asset_file(path.join(self.srcdir, src),
                                path.join(self.outdir, dest))
            self.info()

        # copy TeX support files from texinputs
        context = {'latex_engine': self.config.latex_engine}
        self.info(bold('copying TeX support files...'))
        staticdirname = path.join(package_dir, 'texinputs')
        for filename in os.listdir(staticdirname):
            if not filename.startswith('.'):
                copy_asset_file(path.join(staticdirname, filename),
                                self.outdir, context=context)

        # copy additional files
        if self.config.latex_additional_files:
            self.info(bold('copying additional files...'), nonl=1)
            for filename in self.config.latex_additional_files:
                self.info(' '+filename, nonl=1)
                copy_asset_file(path.join(self.confdir, filename), self.outdir)
            self.info()

        # the logo is handled differently
        if self.config.latex_logo:
            if not path.isfile(path.join(self.confdir, self.config.latex_logo)):
                raise SphinxError('logo file %r does not exist' % self.config.latex_logo)
            else:
                copy_asset_file(path.join(self.confdir, self.config.latex_logo), self.outdir)
        self.info('done')

    def finish(self):
        # type: () -> None
        self.copy_image_files()

        # copy TeX support files from texinputs
        context = {'latex_engine': self.config.latex_engine}
        logger.info(bold('copying TeX support files...'))
        staticdirname = path.join(package_dir, 'texinputs')
        for filename in os.listdir(staticdirname):
            if not filename.startswith('.'):
                copy_asset_file(path.join(staticdirname, filename),
                                self.outdir, context=context)

        # use pre-1.6.x Makefile for make latexpdf on Windows
        if os.name == 'nt':
            staticdirname = path.join(package_dir, 'texinputs_win')
            copy_asset_file(path.join(staticdirname, 'Makefile_t'),
                            self.outdir, context=context)

        # copy additional files
        if self.config.latex_additional_files:
            logger.info(bold('copying additional files...'), nonl=1)
            for filename in self.config.latex_additional_files:
                logger.info(' ' + filename, nonl=1)
                copy_asset_file(path.join(self.confdir, filename), self.outdir)
            logger.info('')

        # the logo is handled differently
        if self.config.latex_logo:
            if not path.isfile(path.join(self.confdir, self.config.latex_logo)):
                raise SphinxError('logo file %r does not exist' % self.config.latex_logo)
            else:
                copy_asset_file(path.join(self.confdir, self.config.latex_logo), self.outdir)
        logger.info('done')

 def copy_image_files(self):
     # type: () -> None
     if self.images:
         stringify_func = ImageAdapter(self.app.env).get_original_image_uri
         for src in status_iterator(self.images, __('copying images... '), "brown",
                                    len(self.images), self.app.verbosity,
                                    stringify_func=stringify_func):
             dest = self.images[src]
             try:
                 copy_asset_file(path.join(self.srcdir, src),
                                 path.join(self.outdir, dest))
             except Exception as err:
                 logger.warning(__('cannot copy image file %r: %s'),
                                path.join(self.srcdir, src), err)

    def write_message_catalog(self):
        # type: () -> None
        formats = self.config.numfig_format
        context = {
            'addtocaptions': r'\@iden',
            'figurename': formats.get('figure', '').split('%s', 1),
            'tablename': formats.get('table', '').split('%s', 1),
            'literalblockname': formats.get('code-block', '').split('%s', 1)
        }

        if self.context['babel'] or self.context['polyglossia']:
            context['addtocaptions'] = r'\addto\captions%s' % self.babel.get_language()

        filename = path.join(package_dir, 'templates', 'latex', 'sphinxmessages.sty_t')
        copy_asset_file(filename, self.outdir, context=context, renderer=LaTeXRenderer())

    def build_toc(self, outdir, outname):
        # type: (unicode, unicode) -> None
        """Write the metainfo file toc.ncx."""
        logger.info('writing %s file...', outname)

        if self.config.epub_tocscope == 'default':
            doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
                                                       self, prune_toctrees=False,
                                                       includehidden=False)
            refnodes = self.get_refnodes(doctree, [])
            self.toc_add_files(refnodes)
        else:
            # 'includehidden'
            refnodes = self.refnodes
        navpoints = self.build_navpoints(refnodes)
        level = max(item['level'] for item in self.refnodes)
        level = min(level, self.config.epub_tocdepth)
        copy_asset_file(path.join(self.template_dir, 'toc.ncx_t'),
                        path.join(outdir, outname),
                        self.toc_metadata(level, navpoints))

    def finish(self):
        # type: () -> None
        self.copy_image_files()
        self.write_message_catalog()

        # copy TeX support files from texinputs
        # configure usage of xindy (impacts Makefile and latexmkrc)
        # FIXME: convert this rather to a confval with suitable default
        #        according to language ? but would require extra documentation
        if self.config.language:
            xindy_lang_option = \
                XINDY_LANG_OPTIONS.get(self.config.language[:2],
                                       '-L general -C utf8 ')
            xindy_cyrillic = self.config.language[:2] in XINDY_CYRILLIC_SCRIPTS
        else:
            xindy_lang_option = '-L english -C utf8 '
            xindy_cyrillic = False
        context = {
            'latex_engine':      self.config.latex_engine,
            'xindy_use':         self.config.latex_use_xindy,
            'xindy_lang_option': xindy_lang_option,
            'xindy_cyrillic':    xindy_cyrillic,
        }
        logger.info(bold(__('copying TeX support files...')))
        staticdirname = path.join(package_dir, 'texinputs')
        for filename in os.listdir(staticdirname):
            if not filename.startswith('.'):
                copy_asset_file(path.join(staticdirname, filename),
                                self.outdir, context=context)

        # use pre-1.6.x Makefile for make latexpdf on Windows
        if os.name == 'nt':
            staticdirname = path.join(package_dir, 'texinputs_win')
            copy_asset_file(path.join(staticdirname, 'Makefile_t'),
                            self.outdir, context=context)

        # copy additional files
        if self.config.latex_additional_files:
            logger.info(bold(__('copying additional files...')), nonl=1)
            for filename in self.config.latex_additional_files:
                logger.info(' ' + filename, nonl=1)
                copy_asset_file(path.join(self.confdir, filename), self.outdir)
            logger.info('')

        # the logo is handled differently
        if self.config.latex_logo:
            if not path.isfile(path.join(self.confdir, self.config.latex_logo)):
                raise SphinxError(__('logo file %r does not exist') % self.config.latex_logo)
            else:
                copy_asset_file(path.join(self.confdir, self.config.latex_logo), self.outdir)
        logger.info(__('done'))

    def build_navigation_doc(self, outdir, outname):
        # type: (unicode, unicode) -> None
        """Write the metainfo file nav.xhtml."""
        logger.info(__('writing %s file...'), outname)

        if self.config.epub_tocscope == 'default':
            doctree = self.env.get_and_resolve_doctree(
                self.config.master_doc, self,
                prune_toctrees=False, includehidden=False)
            refnodes = self.get_refnodes(doctree, [])
            self.toc_add_files(refnodes)
        else:
            # 'includehidden'
            refnodes = self.refnodes
        navlist = self.build_navlist(refnodes)
        copy_asset_file(path.join(self.template_dir, 'nav.xhtml_t'),
                        path.join(outdir, outname),
                        self.navigation_doc_metadata(navlist))

        # Add nav.xhtml to epub file
        if outname not in self.files:
            self.files.append(outname)

def test_copy_asset_file(tempdir):
    renderer = DummyTemplateLoader()

    # copy normal file
    src = (tempdir / 'asset.txt')
    src.write_text('# test data')
    dest = (tempdir / 'output.txt')

    copy_asset_file(src, dest)
    assert dest.exists()
    assert src.text() == dest.text()

    # copy template file
    src = (tempdir / 'asset.txt_t')
    src.write_text('# {{var1}} data')
    dest = (tempdir / 'output.txt_t')

    copy_asset_file(src, dest, {'var1': 'template'}, renderer)
    assert not dest.exists()
    assert (tempdir / 'output.txt').exists()
    assert (tempdir / 'output.txt').text() == '# template data'

    # copy template file to subdir
    src = (tempdir / 'asset.txt_t')
    src.write_text('# {{var1}} data')
    subdir1 = (tempdir / 'subdir')
    subdir1.makedirs()

    copy_asset_file(src, subdir1, {'var1': 'template'}, renderer)
    assert (subdir1 / 'asset.txt').exists()
    assert (subdir1 / 'asset.txt').text() == '# template data'

    # copy template file without context
    src = (tempdir / 'asset.txt_t')
    subdir2 = (tempdir / 'subdir2')
    subdir2.makedirs()

    copy_asset_file(src, subdir2)
    assert not (subdir2 / 'asset.txt').exists()
    assert (subdir2 / 'asset.txt_t').exists()
    assert (subdir2 / 'asset.txt_t').text() == '# {{var1}} data'