def fixup_keywords(app, exception):
    # only works for .chm output
    if getattr(app.builder, 'name', '') != 'htmlhelp' or exception:
        return

    getLogger(__name__).info('fixing HTML escapes in keywords file...')
    outdir = app.builder.outdir
    outname = app.builder.config.htmlhelp_basename
    with app.builder.open_file(outdir, outname + '.hhk', 'r') as f:
        index = f.read()
    with app.builder.open_file(outdir, outname + '.hhk', 'w') as f:
        f.write(index.replace(''', '''))

 def _warn_if_undocumented(self):
     document = self.state.document
     config = document.settings.env.config
     report = config.report_undocumented_coq_objects
     if report and not self.content and "undocumented" not in self.options:
         # This is annoyingly convoluted, but we don't want to raise warnings
         # or interrupt the generation of the current node.  For more details
         # see https://github.com/sphinx-doc/sphinx/issues/4976.
         msg = 'No contents in directive {}'.format(self.name)
         node = document.reporter.info(msg, line=self.lineno)
         getLogger(__name__).info(node.astext())
         if report == "warning":
             raise self.warning(msg)

    def test_docassert_html_method(self):
        fLOG(
            __file__,
            self._testMethodName,
            OutputPrint=__name__ == "__main__")

        class MyStream:
            def __init__(self):
                self.rows = []

            def write(self, text):
                fLOG(
                    "[warning*] {0} - '{1}'".format(len(self), text.strip("\n\r ")))
                self.rows.append(text)

            def getvalue(self):
                return "\n".join(self.rows)

            def __len__(self):
                return len(self.rows)

        logger1 = getLogger("MockSphinxApp")
        logger2 = getLogger("docassert")
        log_capture_string = MyStream()  # StringIO()
        ch = logging.StreamHandler(log_capture_string)
        ch.setLevel(logging.DEBUG)
        logger1.logger.addHandler(ch)
        logger2.logger.addHandler(ch)
        logger2.warning("try")

        this = os.path.abspath(os.path.dirname(__file__))
        data = os.path.join(this, "datadoc")
        with sys_path_append(data):
            obj, name = import_object("exsig.clex.onemethod", "method")
            newstring = ".. automethod:: exsig.clex.onemethod"
            html = rst2html(newstring)
            self.assertTrue(html is not None)
        fLOG(len(log_capture_string))

        lines = log_capture_string.getvalue().split("\n")
        if len(lines) == 0:
            raise Exception("no warning")
        nb = 0
        for line in lines:
            if "'onemethod' has no parameter 'c'" in line:
                nb += 1
        if nb == 0:
            raise Exception("not the right warning")
        for line in lines:
            if "'onemethod' has undocumented parameters 'b, self'" in line:
                raise Exception(line)

def build_cli_examples(_):
    logger = logging.getLogger('cli-examples')

    clidir = os.path.join(SPHINX_DIR, 'cli')
    exini = os.path.join(clidir, 'examples.ini')
    exdir = os.path.join(clidir, 'examples')
    if not os.path.isdir(exdir):
        os.makedirs(exdir)

    config = ConfigParser()
    config.read(exini)

    rsts = []
    for sect in config.sections():
        rst, cmd = _build_cli_example(config, sect, exdir, logger)
        if cmd:
            logger.info('[cli] running example {0!r}'.format(sect))
            logger.debug('[cli] $ {0}'.format(cmd))
            subprocess.check_call(cmd, shell=True)
            logger.debug('[cli] wrote {0}'.format(cmd.split()[-1]))
        rsts.append(rst)

    with open(os.path.join(exdir, 'examples.rst'), 'w') as f:
        f.write('.. toctree::\n   :glob:\n\n')
        for rst in rsts:
            f.write('   {0}\n'.format(rst[len(SPHINX_DIR):]))

def test_suppress_warnings(app, status, warning):
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    app._warncount = 0  # force reset

    app.config.suppress_warnings = []
    warning.truncate(0)
    logger.warning('message1', type='test', subtype='logging')
    logger.warning('message2', type='test', subtype='crash')
    logger.warning('message3', type='actual', subtype='logging')
    assert 'message1' in warning.getvalue()
    assert 'message2' in warning.getvalue()
    assert 'message3' in warning.getvalue()
    assert app._warncount == 3

    app.config.suppress_warnings = ['test']
    warning.truncate(0)
    logger.warning('message1', type='test', subtype='logging')
    logger.warning('message2', type='test', subtype='crash')
    logger.warning('message3', type='actual', subtype='logging')
    assert 'message1' not in warning.getvalue()
    assert 'message2' not in warning.getvalue()
    assert 'message3' in warning.getvalue()
    assert app._warncount == 4

    app.config.suppress_warnings = ['test.logging']
    warning.truncate(0)
    logger.warning('message1', type='test', subtype='logging')
    logger.warning('message2', type='test', subtype='crash')
    logger.warning('message3', type='actual', subtype='logging')
    assert 'message1' not in warning.getvalue()
    assert 'message2' in warning.getvalue()
    assert 'message3' in warning.getvalue()
    assert app._warncount == 6

def depart_fitb_node(self, node):
    # If there were fewer blanks than feedback items, add blanks at the end of the question.
    blankCount = 0
    for _ in node.traverse(BlankNode):
        blankCount += 1
    while blankCount < len(node.feedbackArray):
        visit_blank_node(self, None)
        blankCount += 1

    # Warn if there are fewer feedback items than blanks.
    if len(node.feedbackArray) < blankCount:
        # Taken from the example in the `logging API <http://www.sphinx-doc.org/en/stable/extdev/logging.html#logging-api>`_.
        logger = logging.getLogger(__name__)
        logger.warning('Not enough feedback for the number of blanks supplied.', location=node)

    # Generate the HTML.
    node.fitb_options['json'] = json.dumps(node.feedbackArray)
    res = node.template_end % node.fitb_options
    self.body.append(res)

    # add HTML to the Database and clean up
    addHTMLToDB(node.fitb_options['divid'],
                node.fitb_options['basecourse'],
                "".join(self.body[self.body.index(node.delimiter) + 1:]))

    self.body.remove(node.delimiter)

def test_info_location(app, status, warning):
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    logger.info('message1', location='index')
    assert 'index.txt: message1' in status.getvalue()

    logger.info('message2', location=('index', 10))
    assert 'index.txt:10: message2' in status.getvalue()

    logger.info('message3', location=None)
    assert '\nmessage3' in status.getvalue()

    node = nodes.Node()
    node.source, node.line = ('index.txt', 10)
    logger.info('message4', location=node)
    assert 'index.txt:10: message4' in status.getvalue()

    node.source, node.line = ('index.txt', None)
    logger.info('message5', location=node)
    assert 'index.txt:: message5' in status.getvalue()

    node.source, node.line = (None, 10)
    logger.info('message6', location=node)
    assert '<unknown>:10: message6' in status.getvalue()

    node.source, node.line = (None, None)
    logger.info('message7', location=node)
    assert '\nmessage7' in status.getvalue()

def test_warning_location(app, status, warning):
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    logger.warning('message1', location='index')
    assert 'index.txt: WARNING: message1' in warning.getvalue()

    logger.warning('message2', location=('index', 10))
    assert 'index.txt:10: WARNING: message2' in warning.getvalue()

    logger.warning('message3', location=None)
    assert colorize('darkred', 'WARNING: message3') in warning.getvalue()

    node = nodes.Node()
    node.source, node.line = ('index.txt', 10)
    logger.warning('message4', location=node)
    assert 'index.txt:10: WARNING: message4' in warning.getvalue()

    node.source, node.line = ('index.txt', None)
    logger.warning('message5', location=node)
    assert 'index.txt:: WARNING: message5' in warning.getvalue()

    node.source, node.line = (None, 10)
    logger.warning('message6', location=node)
    assert '<unknown>:10: WARNING: message6' in warning.getvalue()

    node.source, node.line = (None, None)
    logger.warning('message7', location=node)
    assert colorize('darkred', 'WARNING: message7') in warning.getvalue()

def test_colored_logs(app, status, warning):
    app.verbosity = 2
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    # default colors
    logger.debug('message1')
    logger.verbose('message2')
    logger.info('message3')
    logger.warning('message4')
    logger.critical('message5')
    logger.error('message6')

    assert colorize('darkgray', 'message1') in status.getvalue()
    assert 'message2\n' in status.getvalue()  # not colored
    assert 'message3\n' in status.getvalue()  # not colored
    assert colorize('darkred', 'WARNING: message4') in warning.getvalue()
    assert 'WARNING: message5\n' in warning.getvalue()  # not colored
    assert 'WARNING: message6\n' in warning.getvalue()  # not colored

    # color specification
    logger.debug('message7', color='white')
    logger.info('message8', color='red')
    assert colorize('white', 'message7') in status.getvalue()
    assert colorize('red', 'message8') in status.getvalue()

def check_parameters(documenter, doc):
    """
    Check that all documented parameters match a formal parameter for the
    function. Documented params which don't match the actual function may be
    typos.
    """
    guessed = set(doc['guessed_params'] or [])
    if not guessed:
        return

    documented = {
        # param name can be of the form [foo.bar.baz=default]\ndescription
        jsdoc.ParamDoc(text).name.split('.')[0]
        for text in doc.get_as_list('param')
    }
    odd = documented - guessed
    if not odd:
        return

    # use sphinx logging API if available, otherwise fall back to warning
    # via the app object (deprecated in 1.6, removed in 2.0)
    # sphinx.util.logging exists in 1.5 but is basically useless
    if hasattr(sphinx_logging, 'getLogger'):
        logger = sphinx_logging.getLogger('autojsdoc').warning
    else:
        logger = documenter.directive.env.app.warn

    logger("Found documented params %s not in formal parameter list "
             "of function %s in module %s (%s)" % (
        ', '.join(odd),
        doc.name,
        documenter.modname,
        doc['sourcemodule']['sourcefile'],
    ))

def build_examples(_):
    logger = logging.getLogger('examples')
    logger.info('[examples] converting examples to RST...')

    srcdir = os.path.join(SPHINX_DIR, os.pardir, 'examples')
    outdir = os.path.join(SPHINX_DIR, 'examples')
    ex2rst = os.path.join(SPHINX_DIR, 'ex2rst.py')

    if not os.path.isdir(outdir):
        os.makedirs(outdir)
        logger.debug('[examples] created {0}'.format(outdir))

    for exdir in next(os.walk(srcdir))[1]:
        subdir = os.path.join(outdir, exdir)
        if not os.path.isdir(subdir):
            os.makedirs(subdir)
        # copy index
        index = os.path.join(subdir, 'index.rst')
        shutil.copyfile(os.path.join(srcdir, exdir, 'index.rst'), index)
        logger.debug('[examples] copied {0}'.format(index))
        # render python script as RST
        for expy in glob.glob(os.path.join(srcdir, exdir, '*.py')):
            target = os.path.join(
                subdir, os.path.basename(expy).replace('.py', '.rst'))
            subprocess.Popen([sys.executable, ex2rst, expy, target])
            logger.debug('[examples] wrote {0}'.format(target))
        logger.info('[examples] converted all in examples/{0}'.format(exdir))

def copy_assets(app, exception):
    """ Copy asset files to the output """
    if 'getLogger' in dir(logging):
        log = logging.getLogger(__name__).info  # pylint: disable=no-member
    else:
        log = app.info
    builders = get_compatible_builders(app)
    if exception:
        return
    if app.builder.name not in builders:
        if not app.config['sphinx_tabs_nowarn']:
            app.warn(
                'Not copying tabs assets! Not compatible with %s builder' %
                app.builder.name)
        return

    log('Copying tabs assets')

    installdir = os.path.join(app.builder.outdir, '_static', 'sphinx_tabs')

    for path in FILES:
        source = resource_filename('sphinx_tabs', path)
        dest = os.path.join(installdir, path)

        destdir = os.path.dirname(dest)
        if not os.path.exists(destdir):
            os.makedirs(destdir)

        copyfile(source, dest)

    def test_docassert_html(self):
        fLOG(
            __file__,
            self._testMethodName,
            OutputPrint=__name__ == "__main__")

        logger1 = getLogger("MockSphinxApp")
        logger2 = getLogger("docassert")

        log_capture_string = StringIO()
        ch = logging.StreamHandler(log_capture_string)
        ch.setLevel(logging.DEBUG)
        logger1.logger.addHandler(ch)
        logger2.logger.addHandler(ch)

        this = os.path.abspath(os.path.dirname(__file__))
        data = os.path.join(this, "datadoc")
        with sys_path_append(data):
            obj, name = import_object("exdocassert.onefunction", "function")
            docstring = obj.__doc__
            with warnings.catch_warnings(record=True) as ws:
                html = rst2html(docstring)
                if "if a and b have different" not in html:
                    raise Exception(html)

            newstring = ".. autofunction:: exdocassert.onefunction"
            with warnings.catch_warnings(record=True) as ws:
                html = rst2html(newstring)
                for i, w in enumerate(ws):
                    fLOG(i, ":", w)
                if "if a and b have different" not in html:
                    html = rst2html(newstring, fLOG=fLOG)
                    fLOG("number of warnings", len(ws))
                    for i, w in enumerate(ws):
                        fLOG(i, ":", str(w).replace("\\n", "\n"))
                    raise Exception(html)

            from docutils.parsers.rst.directives import _directives
            self.assertTrue("autofunction" in _directives)

        lines = log_capture_string.getvalue().split("\n")
        if len(lines) > 0:
            for line in lines:
                if "'onefunction' has no parameter 'TypeError'" in line:
                    raise Exception(
                        "This warning should not happen.\n{0}".format("\n".join(lines)))
        self.assertTrue("<strong>a</strong>" in html)

def warning(context, message, *args, **kwargs):
    # type: (Dict, unicode, Any, Any) -> unicode
    if 'pagename' in context:
        filename = context.get('pagename') + context.get('file_suffix', '')
        message = 'in rendering %s: %s' % (filename, message)
    logger = logging.getLogger('sphinx.themes')
    logger.warning(message, *args, **kwargs)
    return ''  # return empty string not to output any values

def test_nonl_info_log(app, status, warning):
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    logger.info('message1', nonl=True)
    logger.info('message2')
    logger.info('message3')

    assert 'message1message2\nmessage3' in status.getvalue()

    def initialize():
        """
        initialize the confluence logger

        Before using the Confluence logger utility class, it needs to be
        initialized. This method should be invoked once (ideally before any
        attempts made to log).
        """
        ConfluenceLogger.logger = logging.getLogger("confluence")

def write_citing_rst(_):
    logger = logging.getLogger('zenodo')
    here = os.path.dirname(__file__)
    with open(os.path.join(here, 'citing.rst.in'), 'r') as fobj:
        citing = fobj.read()
    citing += '\n' + zenodo.format_citations(597016)
    out = os.path.join(here, 'citing.rst')
    with open(out, 'w') as f:
        f.write(citing)
    logger.info('[zenodo] wrote {0}'.format(out))

def test_verbosity_filter(app, status, warning):
    # verbosity = 0: INFO
    app.verbosity = 0
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    logger.info('message1')
    logger.verbose('message2')
    logger.debug('message3')

    assert 'message1' in status.getvalue()
    assert 'message2' not in status.getvalue()
    assert 'message3' not in status.getvalue()
    assert 'message4' not in status.getvalue()

    # verbosity = 1: VERBOSE
    app.verbosity = 1
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    logger.info('message1')
    logger.verbose('message2')
    logger.debug('message3')

    assert 'message1' in status.getvalue()
    assert 'message2' in status.getvalue()
    assert 'message3' not in status.getvalue()
    assert 'message4' not in status.getvalue()

    # verbosity = 2: DEBUG
    app.verbosity = 2
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    logger.info('message1')
    logger.verbose('message2')
    logger.debug('message3')

    assert 'message1' in status.getvalue()
    assert 'message2' in status.getvalue()
    assert 'message3' in status.getvalue()
    assert 'message4' not in status.getvalue()

def test_warningiserror(app, status, warning):
    logging.setup(app, status, warning)
    logger = logging.getLogger(__name__)

    # if False, warning is not error
    app.warningiserror = False
    logger.warning('message')

    # if True, warning raises SphinxWarning exception
    app.warningiserror = True
    with pytest.raises(SphinxWarning):
        logger.warning('message')

 def setup(app):
     msg = ('The sphinx_gallery extension is not installed, so the '
            'gallery will not be built.  You will probably see '
            'additional warnings about undefined references due '
            'to this.')
     try:
         app.warn(msg)
     except AttributeError:
         # Sphinx 1.6+
         from sphinx.util import logging
         logger = logging.getLogger(__name__)
         logger.warning(msg)