def test_needs_extensions(app):
# empty needs_extensions
assert app.config.needs_extensions == {}
verify_needs_extensions(app, app.config)
# needs_extensions fulfilled
app.config.needs_extensions = {'test.extension': '3.9'}
app.extensions['test.extension'] = Extension('test.extension', 'test.extension', version='3.10')
verify_needs_extensions(app, app.config)
# needs_extensions not fulfilled
app.config.needs_extensions = {'test.extension': '3.11'}
app.extensions['test.extension'] = Extension('test.extension', 'test.extension', version='3.10')
with pytest.raises(VersionRequirementError):
verify_needs_extensions(app, app.config)
def load_extension(self, app, extname):
# type: (Sphinx, unicode) -> None
"""Load a Sphinx extension."""
if extname in app.extensions: # alread loaded
return
if extname in EXTENSION_BLACKLIST:
logger.warning(
__('the extension %r was already merged with Sphinx since '
'version %s; this extension is ignored.'), extname,
EXTENSION_BLACKLIST[extname])
return
# update loading context
app._setting_up_extension.append(extname)
try:
mod = __import__(extname, None, None, ['setup'])
except ImportError as err:
logger.verbose(
__('Original exception:\n') + traceback.format_exc())
raise ExtensionError(
__('Could not import extension %s') % extname, err)
if not hasattr(mod, 'setup'):
logger.warning(
__('extension %r has no setup() function; is it really '
'a Sphinx extension module?'), extname)
metadata = {} # type: Dict[unicode, Any]
else:
try:
metadata = mod.setup(app)
except VersionRequirementError as err:
# add the extension name to the version required
raise VersionRequirementError(
__('The %s extension used by this project needs at least '
'Sphinx v%s; it therefore cannot be built with this '
'version.') % (extname, err))
if metadata is None:
metadata = {}
if extname == 'rst2pdf.pdfbuilder':
metadata['parallel_read_safe'] = True
elif not isinstance(metadata, dict):
logger.warning(
__('extension %r returned an unsupported object from '
'its setup() function; it should return None or a '
'metadata dictionary'), extname)
app.extensions[extname] = Extension(extname, mod, **metadata)
app._setting_up_extension.pop()
def load_extension(self, app: "Sphinx", extname: str) -> None:
"""Load a Sphinx extension."""
if extname in app.extensions: # already loaded
return
if extname in EXTENSION_BLACKLIST:
logger.warning(
__('the extension %r was already merged with Sphinx since '
'version %s; this extension is ignored.'), extname,
EXTENSION_BLACKLIST[extname])
return
# update loading context
prefix = __('while setting up extension %s:') % extname
with prefixed_warnings(prefix):
try:
mod = import_module(extname)
except ImportError as err:
logger.verbose(
__('Original exception:\n') + traceback.format_exc())
raise ExtensionError(
__('Could not import extension %s') % extname,
err) from err
setup = getattr(mod, 'setup', None)
if setup is None:
logger.warning(
__('extension %r has no setup() function; is it really '
'a Sphinx extension module?'), extname)
metadata = {} # type: Dict[str, Any]
else:
try:
metadata = setup(app)
except VersionRequirementError as err:
# add the extension name to the version required
raise VersionRequirementError(
__('The %s extension used by this project needs at least '
'Sphinx v%s; it therefore cannot be built with this '
'version.') % (extname, err)) from err
if metadata is None:
metadata = {}
elif not isinstance(metadata, dict):
logger.warning(
__('extension %r returned an unsupported object from '
'its setup() function; it should return None or a '
'metadata dictionary'), extname)
metadata = {}
app.extensions[extname] = Extension(extname, mod, **metadata)
def custom_setup(app, author):
"""
See `Sphinx core events <https://www.sphinx-doc.org/en/master/#sphinx-core-events>`_.
"""
from ..sphinxext.sphinx_bigger_extension import setup as setup_bigger
from ..sphinxext.sphinx_githublink_extension import setup as setup_githublink
from ..sphinxext.sphinx_blog_extension import setup as setup_blogpost
from ..sphinxext.sphinx_blocref_extension import setup as setup_blocref
from ..sphinxext.sphinx_exref_extension import setup as setup_exref
from ..sphinxext.sphinx_faqref_extension import setup as setup_faqref
from ..sphinxext.sphinx_gitlog_extension import setup as setup_gitlog
from ..sphinxext.sphinx_mathdef_extension import setup as setup_mathdef
from ..sphinxext.sphinx_quote_extension import setup as setup_quote
from ..sphinxext.sphinx_nbref_extension import setup as setup_nbref
from ..sphinxext.sphinx_runpython_extension import setup as setup_runpython
from ..sphinxext.sphinx_downloadlink_extension import setup as setup_downloadlink
from ..sphinxext.sphinx_video_extension import setup as setup_video
from ..sphinxext.sphinx_image_extension import setup as setup_simpleimage
from ..sphinxext.sphinx_todoext_extension import setup as setup_todoext
from ..sphinxext.sphinx_docassert_extension import setup as setup_docassert
from ..sphinxext.sphinx_autosignature import setup as setup_signature
from ..sphinxext.sphinx_template_extension import setup as setup_tpl
from ..sphinxext.sphinx_cmdref_extension import setup as setup_cmdref
from ..sphinxext.sphinx_postcontents_extension import setup as setup_postcontents
from ..sphinxext.sphinx_tocdelay_extension import setup as setup_tocdelay
from ..sphinxext.sphinx_sharenet_extension import setup as setup_sharenet
from ..sphinxext.sphinx_youtube_extension import setup as setup_youtube
from ..sphinxext.sphinx_epkg_extension import setup as setup_epkg
from ..sphinxext import setup_image
from ..sphinxext.sphinx_toctree_extension import setup as setup_toctree
from ..sphinxext.sphinx_collapse_extension import setup as setup_collapse
from ..sphinxext.sphinx_gdot_extension import setup as setup_gdot
# delayed import to speed up import time
from sphinx.errors import ExtensionError
from sphinx.extension import Extension
try:
app.connect("autodoc-skip-member", _skip)
except ExtensionError as e: # pragma: no cover
# No event autodoc-skip-member.
warnings.warn("Sphinx extension error {0}".format(e), RuntimeError)
if 'author' not in app.config.values:
app.add_config_value('author', author, True)
exts = [setup_toctree, setup_runpython, setup_bigger,
setup_githublink, setup_sharenet, setup_video,
setup_simpleimage, setup_todoext, setup_blogpost,
setup_mathdef, setup_blocref, setup_exref,
setup_faqref, setup_nbref, setup_cmdref,
setup_signature, setup_docassert, setup_postcontents,
setup_tocdelay, setup_youtube, setup_tpl,
setup_epkg, setup_image, setup_collapse, setup_gdot,
setup_downloadlink, setup_quote, setup_gitlog]
for ext in exts:
meta = ext(app)
name = ext.__name__.rsplit('.', maxsplit=1)[-1].replace("setup_", "")
if name == "image":
name = "pyquickhelper.sphinxext.sphinximages.sphinxtrib.images"
else:
name = 'pyquickhelper.sphinxext.sphinx_%s_extension' % name
app.extensions[name] = Extension(name, ext.__module__, **meta)
try:
import bokeh
assert bokeh is not None
from ..sphinxext.bokeh.bokeh_plot import setup as setup_bokeh
setup_bokeh(app)
name = "pyquickhelper.sphinxext.bokeh.bokeh_plot"
app.extensions[name] = Extension(name, setup_bokeh.__module__)
except ImportError: # pragma: no cover
# bokeh is not installed.
pass
# from sphinx.util.texescape import tex_replacements
# tex_replacements += [('oe', '\\oe '), ]
app.add_js_file("require.js")
# style for notebooks
app.add_css_file(style_figure_notebook[0])
return app