162 lines
6.9 KiB
Python
162 lines
6.9 KiB
Python
|
# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
|
||
|
|
|
||
|
|
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
|
|
# of this software and associated documentation files (the "Software"), to
|
||
|
|
# deal in the Software without restriction, including without limitation the
|
||
|
|
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
||
|
|
# sell copies of the Software, and to permit persons to whom the Software is
|
||
|
|
# furnished to do so, subject to the following conditions:
|
||
|
|
|
||
|
|
# The above copyright notice and this permission notice shall be included in
|
||
|
|
# all copies or substantial portions of the Software.
|
||
|
|
|
||
|
|
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
|
|
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
|
|
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
|
||
|
|
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
|
|
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||
|
|
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
||
|
|
# IN THE SOFTWARE.
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
import logging
|
||
|
|
|
||
|
|
from collections.abc import Callable
|
||
|
|
from mkdocs.config.config_options import Plugins
|
||
|
|
from mkdocs.config.defaults import MkDocsConfig
|
||
|
|
from mkdocs.exceptions import PluginError
|
||
|
|
from mkdocs.plugins import BasePlugin, event_priority
|
||
|
|
|
||
|
|
from .config import GroupConfig
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# Classes
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
# Group plugin
|
||
|
|
class GroupPlugin(BasePlugin[GroupConfig]):
|
||
|
|
supports_multiple_instances = True
|
||
|
|
|
||
|
|
# Initialize plugin
|
||
|
|
def __init__(self, *args, **kwargs):
|
||
|
|
super().__init__(*args, **kwargs)
|
||
|
|
|
||
|
|
# Initialize object attributes
|
||
|
|
self.is_serve = False
|
||
|
|
self.is_dirty = False
|
||
|
|
|
||
|
|
# Determine whether we're serving the site
|
||
|
|
def on_startup(self, *, command, dirty):
|
||
|
|
self.is_serve = command == "serve"
|
||
|
|
self.is_dirty = dirty
|
||
|
|
|
||
|
|
# If the group is enabled, conditionally load plugins - at first, this might
|
||
|
|
# sound easier than it actually is, as we need to jump through some hoops to
|
||
|
|
# ensure correct ordering among plugins. We're effectively initializing the
|
||
|
|
# plugins that are part of the group after all MkDocs finished initializing
|
||
|
|
# all other plugins, so we need to patch the order of the methods. Moreover,
|
||
|
|
# we must use MkDocs existing plugin collection, or we might have collisions
|
||
|
|
# with other plugins that are not part of the group. As so often, this is a
|
||
|
|
# little hacky, but has huge potential making plugin configuration easier.
|
||
|
|
# There's one little caveat: the `__init__` and `on_startup` methods of the
|
||
|
|
# plugins that are part of the group are called after all other plugins, so
|
||
|
|
# the `event_priority` decorator for `on_startup` methods is effectively
|
||
|
|
# useless. However, the `on_startup` method is only intended to set up the
|
||
|
|
# plugin and doesn't receive anything else than the invoked command and
|
||
|
|
# whether we're running a dirty build, so there should be no problems.
|
||
|
|
@event_priority(150)
|
||
|
|
def on_config(self, config):
|
||
|
|
if not self.config.enabled:
|
||
|
|
return
|
||
|
|
|
||
|
|
# Retrieve plugin collection from configuration
|
||
|
|
option: Plugins = dict(config._schema)["plugins"]
|
||
|
|
assert isinstance(option, Plugins)
|
||
|
|
|
||
|
|
# Load all plugins in group
|
||
|
|
self.plugins: dict[str, BasePlugin] = {}
|
||
|
|
try:
|
||
|
|
for name, plugin in self._load(option):
|
||
|
|
self.plugins[name] = plugin
|
||
|
|
|
||
|
|
# The plugin could not be loaded, likely because it's not installed or
|
||
|
|
# misconfigured, so we raise a plugin error for a nicer error message
|
||
|
|
except Exception as e:
|
||
|
|
raise PluginError(str(e))
|
||
|
|
|
||
|
|
# Patch order of plugin methods
|
||
|
|
for events in option.plugins.events.values():
|
||
|
|
self._patch(events, config)
|
||
|
|
|
||
|
|
# Invoke `on_startup` event for plugins in group
|
||
|
|
command = "serve" if self.is_serve else "build"
|
||
|
|
for method in option.plugins.events["startup"]:
|
||
|
|
plugin = self._get_plugin(method)
|
||
|
|
|
||
|
|
# Ensure that we have a method bound to a plugin (and not a hook)
|
||
|
|
if plugin and plugin in self.plugins.values():
|
||
|
|
method(command = command, dirty = self.is_dirty)
|
||
|
|
|
||
|
|
# -------------------------------------------------------------------------
|
||
|
|
|
||
|
|
# Retrieve plugin instance for bound method or nothing
|
||
|
|
def _get_plugin(self, method: Callable):
|
||
|
|
return getattr(method, "__self__", None)
|
||
|
|
|
||
|
|
# Retrieve priority of plugin method
|
||
|
|
def _get_priority(self, method: Callable):
|
||
|
|
return getattr(method, "mkdocs_priority", 0)
|
||
|
|
|
||
|
|
# Retrieve position of plugin
|
||
|
|
def _get_position(self, plugin: BasePlugin, config: MkDocsConfig) -> int:
|
||
|
|
for at, (_, candidate) in enumerate(config.plugins.items()):
|
||
|
|
if plugin == candidate:
|
||
|
|
return at
|
||
|
|
|
||
|
|
# -------------------------------------------------------------------------
|
||
|
|
|
||
|
|
# Load plugins that are part of the group
|
||
|
|
def _load(self, option: Plugins):
|
||
|
|
for name, data in option._parse_configs(self.config.plugins):
|
||
|
|
yield option.load_plugin_with_namespace(name, data)
|
||
|
|
|
||
|
|
# -------------------------------------------------------------------------
|
||
|
|
|
||
|
|
# Patch order of plugin methods - all other plugin methods are already in
|
||
|
|
# the right order, so we only need to check those that are part of the group
|
||
|
|
# and bubble them up into the right location. Some plugin methods may define
|
||
|
|
# priorities, so we need to make sure to order correctly within those.
|
||
|
|
def _patch(self, methods: list[Callable], config: MkDocsConfig):
|
||
|
|
position = self._get_position(self, config)
|
||
|
|
for at in reversed(range(1, len(methods))):
|
||
|
|
tail = methods[at - 1]
|
||
|
|
head = methods[at]
|
||
|
|
|
||
|
|
# Skip if the plugin is not part of the group
|
||
|
|
plugin = self._get_plugin(head)
|
||
|
|
if not plugin or plugin not in self.plugins.values():
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Skip if the previous method has a higher priority than the current
|
||
|
|
# one, because we know we can't swap them anyway
|
||
|
|
if self._get_priority(tail) > self._get_priority(head):
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Ensure that we have a method bound to a plugin (and not a hook)
|
||
|
|
plugin = self._get_plugin(tail)
|
||
|
|
if not plugin:
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Both methods have the same priority, so we check if the ordering
|
||
|
|
# of both methods is violated, and if it is, swap them
|
||
|
|
if (position < self._get_position(plugin, config)):
|
||
|
|
methods[at], methods[at - 1] = tail, head
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# Data
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
# Set up logging
|
||
|
|
log = logging.getLogger("mkdocs.material.group")
|