File: theme.py

package info (click to toggle)
python-mkdocs 1.6.1%2Bdfsg1-2
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 7,812 kB
  • sloc: python: 14,346; javascript: 10,535; perl: 143; sh: 57; makefile: 30; xml: 11
file content (166 lines) | stat: -rw-r--r-- 5,304 bytes parent folder | download
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