1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
|
from __future__ import annotations
import logging
import os
import warnings
from typing import Any, Collection, MutableMapping
import jinja2
import yaml
try:
from yaml import CSafeLoader as SafeLoader
except ImportError: # pragma: no cover
from yaml import SafeLoader # type: ignore
from mkdocs import localization, utils
from mkdocs.config.base import ValidationError
from mkdocs.utils import templates
log = logging.getLogger(__name__)
class Theme(MutableMapping[str, Any]):
"""
A Theme object.
Args:
name: The name of the theme as defined by its entrypoint.
custom_dir: User defined directory for custom templates.
static_templates: A list of templates to render as static pages.
All other keywords are passed as-is and made available as a key/value mapping.
"""
def __init__(
self,
name: str | None = None,
*,
custom_dir: str | None = None,
static_templates: Collection[str] = (),
locale: str | None = None,
**user_config,
) -> None:
self.name = name
self._custom_dir = custom_dir
_vars: dict[str, Any] = {'name': name, 'locale': 'en'}
self.__vars = _vars
# MkDocs provided static templates are always included
package_dir = os.path.abspath(os.path.dirname(__file__))
mkdocs_templates = os.path.join(package_dir, 'templates')
self.static_templates = set(os.listdir(mkdocs_templates))
# Build self.dirs from various sources in order of precedence
self.dirs = []
if custom_dir is not None:
self.dirs.append(custom_dir)
if name:
self._load_theme_config(name)
# Include templates provided directly by MkDocs (outside any theme)
self.dirs.append(mkdocs_templates)
# Handle remaining user configs. Override theme configs (if set)
self.static_templates.update(static_templates)
_vars.update(user_config)
# Validate locale and convert to Locale object
if locale is None:
locale = _vars['locale']
_vars['locale'] = localization.parse_locale(locale)
name: str | None
@property
def locale(self) -> localization.Locale:
return self['locale']
@property
def custom_dir(self) -> str | None:
return self._custom_dir
@property
def _vars(self) -> dict[str, Any]:
warnings.warn(
"Do not access Theme._vars, instead access the keys of Theme directly.",
DeprecationWarning,
)
return self.__vars
dirs: list[str]
static_templates: set[str]
def __repr__(self) -> str:
return "{}(name={!r}, dirs={!r}, static_templates={!r}, {})".format(
self.__class__.__name__,
self.name,
self.dirs,
self.static_templates,
', '.join(f'{k}={v!r}' for k, v in self.items()),
)
def __getitem__(self, key: str) -> Any:
return self.__vars[key]
def __setitem__(self, key: str, value):
self.__vars[key] = value
def __delitem__(self, key: str):
del self.__vars[key]
def __contains__(self, item: object) -> bool:
return item in self.__vars
def __len__(self):
return len(self.__vars)
def __iter__(self):
return iter(self.__vars)
def _load_theme_config(self, name: str) -> None:
"""Recursively load theme and any parent themes."""
theme_dir = utils.get_theme_dir(name)
utils.get_themes.cache_clear()
self.dirs.append(theme_dir)
try:
file_path = os.path.join(theme_dir, 'mkdocs_theme.yml')
with open(file_path, 'rb') as f:
theme_config = yaml.load(f, SafeLoader)
except OSError as e:
log.debug(e)
raise ValidationError(
f"The theme '{name}' does not appear to have a configuration file. "
f"Please upgrade to a current version of the theme."
)
if theme_config is None:
theme_config = {}
log.debug(f"Loaded theme configuration for '{name}' from '{file_path}': {theme_config}")
if parent_theme := theme_config.pop('extends', None):
themes = utils.get_theme_names()
if parent_theme not in themes:
raise ValidationError(
f"The theme '{name}' inherits from '{parent_theme}', which does not appear to be installed. "
f"The available installed themes are: {', '.join(themes)}"
)
self._load_theme_config(parent_theme)
self.static_templates.update(theme_config.pop('static_templates', []))
self.__vars.update(theme_config)
def get_env(self) -> jinja2.Environment:
"""Return a Jinja environment for the theme."""
loader = jinja2.FileSystemLoader(self.dirs)
# No autoreload because editing a template in the middle of a build is not useful.
env = jinja2.Environment(loader=loader, auto_reload=False)
env.filters['url'] = templates.url_filter
env.filters['script_tag'] = templates.script_tag_filter
localization.install_translations(env, self.locale, self.dirs)
return env
|