def on_config(self, config: Config, **kwargs) -> Config:
"""
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.extension.MkdocstringsExtension]
and add it to the list of Markdown extensions used by `mkdocs`.
We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it
later when processing markdown to get handlers and their global configurations).
"""
log.debug("mkdocstrings.plugin: Adding extension to the list")
theme_name = None
if config["theme"].name is None:
theme_name = os.path.dirname(config["theme"].dirs[0])
else:
theme_name = config["theme"].name
extension_config = {
"theme_name": theme_name,
"mdx": config["markdown_extensions"],
"mdx_configs": config["mdx_configs"],
"mkdocstrings": self.config,
}
self.mkdocstrings_extension = MkdocstringsExtension(config=extension_config)
config["markdown_extensions"].append(self.mkdocstrings_extension)
return config
def on_config(self, config: Config, **kwargs) -> Config:
"""
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.extension.MkdocstringsExtension]
and add it to the list of Markdown extensions used by `mkdocs`.
We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it
later when processing markdown to get handlers and their global configurations).
"""
if not config["site_url"]:
raise ConfigurationError(
"mkdocstrings.plugin: configuration item 'site_url' is required for cross-references"
)
log.debug("mkdocstrings.plugin: Adding extension to the list")
extension_config = {
"theme_name": config["theme"].name,
"mdx": config["markdown_extensions"],
"mdx_configs": config["mdx_configs"],
"mkdocstrings": self.config,
}
self.mkdocstrings_extension = MkdocstringsExtension(config=extension_config)
config["markdown_extensions"].append(self.mkdocstrings_extension)
return config
def on_config(self, config: Config,
**kwargs) -> Config: # noqa: W0613 (unused arguments)
"""Instantiate our Markdown extension.
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.extension.MkdocstringsExtension]
and add it to the list of Markdown extensions used by `mkdocs`.
We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it
later when processing markdown to get handlers and their global configurations).
Arguments:
config: The MkDocs config object.
kwargs: Additional arguments passed by MkDocs.
Returns:
The modified config.
"""
log.debug("Adding extension to the list")
theme_name = None
if config["theme"].name is None:
theme_name = os.path.dirname(config["theme"].dirs[0])
else:
theme_name = config["theme"].name
extension_config = {
"theme_name": theme_name,
"mdx": config["markdown_extensions"],
"mdx_configs": config["mdx_configs"],
"mkdocstrings": self.config,
}
self._handlers = Handlers(extension_config)
try:
# If autorefs plugin is explicitly enabled, just use it.
autorefs = config["plugins"]["autorefs"]
log.debug(f"Picked up existing autorefs instance {autorefs!r}")
except KeyError:
# Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
autorefs = AutorefsPlugin()
autorefs.scan_toc = False
config["plugins"]["autorefs"] = autorefs
log.debug(f"Added a subdued autorefs instance {autorefs!r}")
# Add collector-based fallback in either case.
autorefs.get_fallback_anchor = self._handlers.get_anchor
mkdocstrings_extension = MkdocstringsExtension(extension_config,
self._handlers,
autorefs)
config["markdown_extensions"].append(mkdocstrings_extension)
config["extra_css"].insert(
0, self.css_filename
) # So that it has lower priority than user files.
return config
def test_render_html_escaped_sequences():
"""Assert HTML-escaped sequences are correctly parsed as XML."""
config = {
"theme_name": "material",
"mdx": [],
"mdx_configs": {},
"mkdocstrings": {"default_handler": "python", "custom_templates": None, "watch": [], "handlers": {}},
}
md = Markdown(extensions=[MkdocstringsExtension(config)])
md.convert("::: tests.fixtures.html_escaped_sequences")
def on_config(self, config: Config,
**kwargs) -> Config: # noqa: W0613 (unused arguments)
"""Instantiate our Markdown extension.
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.extension.MkdocstringsExtension]
and add it to the list of Markdown extensions used by `mkdocs`.
We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it
later when processing markdown to get handlers and their global configurations).
Arguments:
config: The MkDocs config object.
kwargs: Additional arguments passed by MkDocs.
Returns:
The modified config.
"""
log.debug("Adding extension to the list")
theme_name = None
if config["theme"].name is None:
theme_name = os.path.dirname(config["theme"].dirs[0])
else:
theme_name = config["theme"].name
to_import: List[Tuple[str, Mapping[str, Any]]] = []
for handler_name, conf in self.config["handlers"].items():
for import_item in conf.pop("import", ()):
if isinstance(import_item, str):
import_item = {"url": import_item}
to_import.append((handler_name, import_item))
extension_config = {
"site_name": config["site_name"],
"theme_name": theme_name,
"mdx": config["markdown_extensions"],
"mdx_configs": config["mdx_configs"],
"mkdocstrings": self.config,
}
self._handlers = Handlers(extension_config)
try:
# If autorefs plugin is explicitly enabled, just use it.
autorefs = config["plugins"]["autorefs"]
log.debug(f"Picked up existing autorefs instance {autorefs!r}")
except KeyError:
# Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
autorefs = AutorefsPlugin()
autorefs.scan_toc = False
config["plugins"]["autorefs"] = autorefs
log.debug(f"Added a subdued autorefs instance {autorefs!r}")
# Add collector-based fallback in either case.
autorefs.get_fallback_anchor = self.handlers.get_anchor
mkdocstrings_extension = MkdocstringsExtension(extension_config,
self.handlers, autorefs)
config["markdown_extensions"].append(mkdocstrings_extension)
config["extra_css"].insert(
0, self.css_filename
) # So that it has lower priority than user files.
self._inv_futures = []
if to_import:
inv_loader = concurrent.futures.ThreadPoolExecutor(4)
for handler_name, import_item in to_import:
future = inv_loader.submit(
self._load_inventory,
self.get_handler(handler_name).load_inventory,
**import_item)
self._inv_futures.append(future)
inv_loader.shutdown(wait=False)
return config