"""The setup for the sphinx extension."""fromtypingimportAnyimportsphinxfromdocutilsimportnodesfromsphinx.applicationimportSphinxfromsphinx.transformsimport(UnreferencedFootnotesDetectorasSphinxUnreferencedFootnotesDetector,)frommyst_parser.mdit_to_docutils.transformsimportUnreferencedFootnotesDetectorfrommyst_parser.parsers.docutils_import(depart_container_html,depart_rubric_html,visit_container_html,visit_rubric_html,)frommyst_parser.warnings_importMystWarnings
[文档]defsetup_sphinx(app:Sphinx,load_parser:bool=False)->None:"""Initialize all settings and transforms in Sphinx. :param app: The Sphinx application object. :param load_parser: Whether to load the parser. """# we do this separately to setup,# so that it can be called by external packages like myst_nbfrommyst_parser.config.mainimportMdParserConfigfrommyst_parser.parsers.sphinx_importMystParserfrommyst_parser.sphinx_ext.directivesimport(FigureMarkdown,SubstitutionReferenceRole,)frommyst_parser.sphinx_ext.mathjaximportoverride_mathjaxfrommyst_parser.sphinx_ext.myst_refsimportMystReferenceResolverifload_parser:app.add_source_suffix(".md","markdown")app.add_source_parser(MystParser)app.add_role("sub-ref",SubstitutionReferenceRole())app.add_directive("figure-md",FigureMarkdown)# TODO currently we globally replace sphinx's transform,# to overcome issues it has (https://github.com/sphinx-doc/sphinx/pull/12730),# but once this PR is merged/released, we should remove thisapp.registry.transforms.remove(SphinxUnreferencedFootnotesDetector)app.add_transform(UnreferencedFootnotesDetector)app.add_post_transform(MystReferenceResolver)# override only the html writer visit methods for rubric, to use the "level" attribute# this allows for nested headers to be correctly renderedifsphinx.version_info<(7,4):# This is now added in sphinx: https://github.com/sphinx-doc/sphinx/pull/12506app.add_node(nodes.rubric,override=True,html=(visit_rubric_html,depart_rubric_html))# override only the html writer visit methods for container,# to remove the "container" class for divs# this avoids CSS clashes with the bootstrap themeapp.add_node(nodes.container,override=True,html=(visit_container_html,depart_container_html),)forname,default,fieldinMdParserConfig().as_triple():if"sphinx"notinfield.metadata.get("omit",[]):# TODO add types?app.add_config_value(f"myst_{name}",default,"env",types=Any)# type: ignore[arg-type]app.connect("builder-inited",create_myst_config)app.connect("builder-inited",override_mathjax)
[文档]defcreate_myst_config(app):"""Create the myst config object and add it to the sphinx environment."""fromsphinx.utilimportloggingfromsphinx.util.consoleimportboldfrommyst_parserimport__version__frommyst_parser.config.mainimportMdParserConfiglogger=logging.getLogger(__name__)values={name:app.config[f"myst_{name}"]forname,_,fieldinMdParserConfig().as_triple()if"sphinx"notinfield.metadata.get("omit",[])}try:app.env.myst_config=MdParserConfig(**values)logger.info(bold("myst v%s:")+" %s",__version__,app.env.myst_config)except(TypeError,ValueError)aserror:logger.error("myst configuration invalid: %s",error.args[0])app.env.myst_config=MdParserConfig()if"attrs_image"inapp.env.myst_config.enable_extensions:logger.warning("The `attrs_image` extension is deprecated, ""please use `attrs_inline` instead.",type="myst",subtype=MystWarnings.DEPRECATED.value,)