mkdocs-mknodes 0.5.4__tar.gz → 0.6.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.pre-commit-config.yaml +2 -2
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/PKG-INFO +2 -3
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/__init__.py +1 -1
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/appconfig/appconfig.py +208 -159
- mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/jinjaconfig.py +60 -0
- mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/themeconfig.py +179 -0
- mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/upathtype.py +178 -0
- mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/validationconfig.py +41 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/cli/__init__.py +15 -14
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/build_page.py +4 -3
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/liveserver.py +9 -27
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/use_cases_section.py +3 -4
- mkdocs_mknodes-0.6.2/mkdocs_mknodes/plugin/mknodesconfig.py +339 -0
- mkdocs_mknodes-0.6.2/mkdocs_mknodes/resources/mkdocs_basic.yml +14 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/pyproject.toml +2 -0
- mkdocs_mknodes-0.5.4/mkdocs_mknodes/mknodesconfig.py +0 -106
- mkdocs_mknodes-0.5.4/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -35
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.editorconfig +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/README.md +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/copilot-instructions.md +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/dependabot.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/workflows/build.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/workflows/documentation.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.gitignore +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/LICENSE +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/README.md +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/configs/mkdocs_mkdocs.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/configs/mkdocs_shared.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/assets/cli.gif +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/build_process.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/cli_index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/github_index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/plugin_configuration.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/use_case_by_config.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/use_case_default_website.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/use_cases_index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/why_should_i_use_mknodes.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/duties.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/appconfig/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/buildcollector.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/buildcontext.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/builders/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/builders/configbuilder.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/cli/richstate.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/serve.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/utils.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/github_index.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/root.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/mkdocsconfig.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/paths.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/pluginconfig.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/py.typed +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/telemetry.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes.sublime-project +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/overrides/_dummy.txt +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/overrides/partials/actions.html +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/conftest.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/data/objects.inv +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/test_build.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/test_cli.py +0 -0
|
@@ -33,10 +33,10 @@ repos:
|
|
|
33
33
|
hooks:
|
|
34
34
|
- id: mypy
|
|
35
35
|
# args: [--ignore-missing-imports]
|
|
36
|
-
additional_dependencies: [mkdocs, orjson]
|
|
36
|
+
additional_dependencies: [mkdocs, orjson, pydantic]
|
|
37
37
|
|
|
38
38
|
- repo: https://github.com/charliermarsh/ruff-pre-commit
|
|
39
|
-
rev: v0.7.
|
|
39
|
+
rev: v0.7.3
|
|
40
40
|
hooks:
|
|
41
41
|
- id: ruff
|
|
42
42
|
- id: ruff-format
|
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: mkdocs-mknodes
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.6.2
|
|
4
4
|
Summary: Don't write docs. Code them.
|
|
5
5
|
Project-URL: Documentation, https://phil65.github.io/mkdocs-mknodes/
|
|
6
6
|
Project-URL: Source, https://github.com/phil65/mkdocs_mknodes
|
|
7
7
|
Project-URL: Gitter, https://app.gitter.im/#/room/#mknodes:gitter.im
|
|
8
8
|
Author-email: Philipp Temminghoff <philipptemminghoff@gmail.com>
|
|
9
|
-
License-Expression: MIT
|
|
10
|
-
License-File: LICENSE
|
|
11
9
|
Keywords: docs,docstrings,documentation,framework,internet,markdown
|
|
12
10
|
Classifier: Development Status :: 4 - Beta
|
|
13
11
|
Classifier: Intended Audience :: Developers
|
|
@@ -37,6 +35,7 @@ Requires-Dist: rich
|
|
|
37
35
|
Requires-Dist: typer
|
|
38
36
|
Requires-Dist: universal-pathlib
|
|
39
37
|
Requires-Dist: yamling
|
|
38
|
+
Requires-Dist: yarl>=1.17.1
|
|
40
39
|
Description-Content-Type: text/markdown
|
|
41
40
|
|
|
42
41
|
``` py title='__main__.create_github_index_md' linenums="86" hl_lines="3"
|
|
@@ -1,16 +1,32 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
|
+
from collections.abc import Callable
|
|
4
|
+
import functools
|
|
3
5
|
import ipaddress
|
|
4
|
-
|
|
6
|
+
import os
|
|
7
|
+
from typing import Annotated, Any, Self
|
|
5
8
|
|
|
9
|
+
from mknodes.utils import classhelpers
|
|
6
10
|
from pathspec import gitignore
|
|
7
|
-
from pydantic import
|
|
11
|
+
from pydantic import (
|
|
12
|
+
BaseModel,
|
|
13
|
+
DirectoryPath,
|
|
14
|
+
Field,
|
|
15
|
+
HttpUrl,
|
|
16
|
+
ValidationInfo,
|
|
17
|
+
field_validator,
|
|
18
|
+
)
|
|
8
19
|
from pydantic.functional_validators import BeforeValidator
|
|
9
20
|
from pydantic_core import PydanticCustomError
|
|
21
|
+
import yamling
|
|
10
22
|
|
|
23
|
+
from mkdocs_mknodes.appconfig import jinjaconfig, themeconfig, validationconfig
|
|
11
24
|
|
|
12
|
-
|
|
25
|
+
|
|
26
|
+
def validate_gitignore_patterns(pattern: list[str] | str) -> str:
|
|
13
27
|
"""Validate a list of gitignore patterns using pathspec."""
|
|
28
|
+
patterns = pattern.splitlines() if isinstance(pattern, str) else pattern
|
|
29
|
+
pattern_str = pattern if isinstance(pattern, str) else "\n".join(pattern)
|
|
14
30
|
try:
|
|
15
31
|
gitignore.GitIgnoreSpec.from_lines(patterns)
|
|
16
32
|
except Exception as e:
|
|
@@ -21,11 +37,11 @@ def validate_gitignore_patterns(patterns: list[str]) -> list[str]:
|
|
|
21
37
|
{"error": str(e)},
|
|
22
38
|
) from e
|
|
23
39
|
else:
|
|
24
|
-
return
|
|
40
|
+
return pattern_str
|
|
25
41
|
|
|
26
42
|
|
|
27
43
|
GitIgnorePatterns = Annotated[
|
|
28
|
-
|
|
44
|
+
str,
|
|
29
45
|
BeforeValidator(validate_gitignore_patterns),
|
|
30
46
|
]
|
|
31
47
|
|
|
@@ -39,109 +55,6 @@ class NavItem(BaseModel):
|
|
|
39
55
|
item: str | dict[str, NavItem]
|
|
40
56
|
|
|
41
57
|
|
|
42
|
-
class ThemeConfig(BaseModel):
|
|
43
|
-
"""Configuration settings for the MkDocs themes.
|
|
44
|
-
|
|
45
|
-
!!! info "Theme Configuration Options"
|
|
46
|
-
The theme configuration allows for extensive customization including custom
|
|
47
|
-
directories, static templates, and locale settings.
|
|
48
|
-
|
|
49
|
-
## Properties Overview
|
|
50
|
-
|
|
51
|
-
| Property | Description | Required |
|
|
52
|
-
|----------|-------------|----------|
|
|
53
|
-
| name | Theme identifier | Yes |
|
|
54
|
-
| custom_dir | Custom theme directory | No |
|
|
55
|
-
| static_templates | Additional static pages | No |
|
|
56
|
-
| locale | Language/locale setting | No |
|
|
57
|
-
"""
|
|
58
|
-
|
|
59
|
-
name: str = Field(...)
|
|
60
|
-
"""Specifies the theme to use for documentation rendering.
|
|
61
|
-
|
|
62
|
-
!!! info "Common Theme Options"
|
|
63
|
-
- `material`: Material for MkDocs theme
|
|
64
|
-
- `mkdocs`: Default MkDocs theme
|
|
65
|
-
- `readthedocs`: ReadTheDocs theme
|
|
66
|
-
|
|
67
|
-
!!! example "Basic Configuration"
|
|
68
|
-
```yaml
|
|
69
|
-
theme:
|
|
70
|
-
name: material
|
|
71
|
-
```
|
|
72
|
-
"""
|
|
73
|
-
|
|
74
|
-
custom_dir: DirectoryPath | None = Field(None)
|
|
75
|
-
"""Directory containing custom theme overrides or extensions.
|
|
76
|
-
|
|
77
|
-
!!! tip "Theme Customization"
|
|
78
|
-
Use this to override or extend the selected theme's templates and assets.
|
|
79
|
-
|
|
80
|
-
!!! example "Custom Directory Setup"
|
|
81
|
-
```yaml
|
|
82
|
-
theme:
|
|
83
|
-
name: material
|
|
84
|
-
custom_dir: custom_theme/
|
|
85
|
-
```
|
|
86
|
-
"""
|
|
87
|
-
|
|
88
|
-
static_templates: list[str] | None = Field(None)
|
|
89
|
-
"""Defines templates to be rendered as static pages, regardless of nav structure.
|
|
90
|
-
|
|
91
|
-
!!! info "Common Use Cases"
|
|
92
|
-
- Error pages (404, 500)
|
|
93
|
-
- Sitemaps
|
|
94
|
-
- Custom static pages
|
|
95
|
-
|
|
96
|
-
!!! example "Static Templates Configuration"
|
|
97
|
-
```yaml
|
|
98
|
-
theme:
|
|
99
|
-
name: material
|
|
100
|
-
static_templates:
|
|
101
|
-
- sitemap.html
|
|
102
|
-
- 404.html
|
|
103
|
-
- custom_page.html
|
|
104
|
-
```
|
|
105
|
-
"""
|
|
106
|
-
|
|
107
|
-
locale: str | None = Field(None)
|
|
108
|
-
"""Defines the language and regional settings for the theme.
|
|
109
|
-
|
|
110
|
-
!!! info "Locale Impact"
|
|
111
|
-
Affects:
|
|
112
|
-
- Date formats
|
|
113
|
-
- UI text translations
|
|
114
|
-
- RTL/LTR text direction
|
|
115
|
-
|
|
116
|
-
!!! example "Locale Setting"
|
|
117
|
-
```yaml
|
|
118
|
-
theme:
|
|
119
|
-
name: material
|
|
120
|
-
locale: en_US
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
!!! tip "Common Locales"
|
|
124
|
-
- `en_US`: English (United States)
|
|
125
|
-
- `fr_FR`: French (France)
|
|
126
|
-
- `de_DE`: German (Germany)
|
|
127
|
-
- `ja_JP`: Japanese (Japan)
|
|
128
|
-
"""
|
|
129
|
-
# Material-related
|
|
130
|
-
# palette: dict[str, Any] | None = Field(
|
|
131
|
-
# None, description="Color palette configuration for the theme."
|
|
132
|
-
# )
|
|
133
|
-
# font: dict[str, Any] | None = Field(
|
|
134
|
-
# None, description="Font configuration for the theme."
|
|
135
|
-
# )
|
|
136
|
-
# features: list[str] | None = Field(
|
|
137
|
-
# None, description="List of theme-specific features to enable."
|
|
138
|
-
# )
|
|
139
|
-
# logo: str | None = Field(None, description="Path to a logo file for the theme.")
|
|
140
|
-
# icon: str | None = Field(None, description="Path to a favicon file.")
|
|
141
|
-
# favicon: str | None = Field(None, description="Path to a favicon file.")
|
|
142
|
-
# language: str | None = Field(None, description="Language for theme localization.")
|
|
143
|
-
|
|
144
|
-
|
|
145
58
|
class PluginConfig(BaseModel):
|
|
146
59
|
"""Configuration for a MkDocs plugin."""
|
|
147
60
|
|
|
@@ -151,6 +64,13 @@ class PluginConfig(BaseModel):
|
|
|
151
64
|
)
|
|
152
65
|
|
|
153
66
|
|
|
67
|
+
class ExtraJavascript(BaseModel):
|
|
68
|
+
path: str
|
|
69
|
+
type: str | None = None
|
|
70
|
+
async_: bool | None = Field(None, alias="async")
|
|
71
|
+
defer: bool | None = None
|
|
72
|
+
|
|
73
|
+
|
|
154
74
|
class AppConfig(BaseModel):
|
|
155
75
|
"""The main configuration class for MkDocs projects.
|
|
156
76
|
|
|
@@ -165,6 +85,18 @@ class AppConfig(BaseModel):
|
|
|
165
85
|
- `theme` configuration
|
|
166
86
|
"""
|
|
167
87
|
|
|
88
|
+
@classmethod
|
|
89
|
+
def from_yaml_file(cls, yaml_path: str | os.PathLike[str], **overrides: Any) -> Self:
|
|
90
|
+
cfg = yamling.load_yaml_file(yaml_path)
|
|
91
|
+
vals = {"config_file_path": str(yaml_path), **cfg, **overrides}
|
|
92
|
+
return cls(**vals)
|
|
93
|
+
|
|
94
|
+
config_file_path: str | None = Field(None, exclude=True)
|
|
95
|
+
inherit: str | None = Field(None, description="", alias="INHERIT")
|
|
96
|
+
"""Define the parent for a configuration file.
|
|
97
|
+
|
|
98
|
+
The path must be relative to the location of the primary file.
|
|
99
|
+
"""
|
|
168
100
|
site_name: str = Field(...)
|
|
169
101
|
"""The primary title for your documentation project.
|
|
170
102
|
|
|
@@ -323,6 +255,83 @@ class AppConfig(BaseModel):
|
|
|
323
255
|
- Staging environments
|
|
324
256
|
"""
|
|
325
257
|
|
|
258
|
+
build_fn: str = "mkdocs_mknodes:parse"
|
|
259
|
+
"""Path to the build script / callable.
|
|
260
|
+
|
|
261
|
+
Possible formats:
|
|
262
|
+
|
|
263
|
+
- `my.module:Class.build_fn` (must be a classmethod / staticmethod)
|
|
264
|
+
- `my.module:build_fn`
|
|
265
|
+
- `path/to/file.py:build_fn`
|
|
266
|
+
|
|
267
|
+
Can also be remote.
|
|
268
|
+
The targeted callable gets the project instance as an argument and optionally
|
|
269
|
+
keyword arguments from setting below.
|
|
270
|
+
"""
|
|
271
|
+
build_fn_arguments: dict[str, Any] | None = None
|
|
272
|
+
"""Keyword arguments passed to the build script / callable.
|
|
273
|
+
|
|
274
|
+
Build scripts may have keyword arguments. You can set them by using this setting.
|
|
275
|
+
"""
|
|
276
|
+
repo_path: str = "."
|
|
277
|
+
"""Path to the repository to create a website for. (`http://....my_project.git`)"""
|
|
278
|
+
clone_depth: int = 100
|
|
279
|
+
"""Clone depth in case the repository is remote. (Required for `git-changelog`)."""
|
|
280
|
+
build_folder: str | None = None
|
|
281
|
+
"""Folder to create the Markdown files in.
|
|
282
|
+
|
|
283
|
+
If no folder is set, **MkNodes** will generate a temporary dir."""
|
|
284
|
+
show_page_info: bool = True
|
|
285
|
+
"""Append an admonition box with build-related information.
|
|
286
|
+
|
|
287
|
+
If True, all pages get added an expandable admonition box at the bottom,
|
|
288
|
+
containing information about the created page.
|
|
289
|
+
This includes:
|
|
290
|
+
- Metadata
|
|
291
|
+
- Resources
|
|
292
|
+
- Code which created the page (needs the page to be created via decorators, or
|
|
293
|
+
the `generated_by` attribute of the `MkPage` needs to be set manually)
|
|
294
|
+
"""
|
|
295
|
+
rewrite_theme_templates: bool = True
|
|
296
|
+
"""Add additional functionality to themes by rewriting template files.
|
|
297
|
+
|
|
298
|
+
MkNodes can rewrite the HTML templates of Themes in order to add additional
|
|
299
|
+
functionality.
|
|
300
|
+
|
|
301
|
+
Right now, enabling this feature allows these options for the **Material-MkDocs**
|
|
302
|
+
theme:
|
|
303
|
+
- use iconify icons instead of the **Material-MkDocs** icons
|
|
304
|
+
- setting the theme features "navigation.indexes" and "navigation.expand" via
|
|
305
|
+
page metadata.
|
|
306
|
+
"""
|
|
307
|
+
auto_delete_generated_templates: bool = True
|
|
308
|
+
"""Delete the generated HTML templates when build is finished.
|
|
309
|
+
|
|
310
|
+
MkNodes may generate HTML template overrides during the build process and
|
|
311
|
+
deletes them after build. Using this setting, the deletion can be prevented.
|
|
312
|
+
"""
|
|
313
|
+
render_by_default: bool = True
|
|
314
|
+
"""Render all pages in the jinja environment.
|
|
315
|
+
|
|
316
|
+
This allows to render jinja in the **MkNodes** environment outside of the `MkJinja`
|
|
317
|
+
nodes.
|
|
318
|
+
|
|
319
|
+
This setting can be overridden by setting the page metadata field "render_macros".
|
|
320
|
+
"""
|
|
321
|
+
global_resources: bool = True
|
|
322
|
+
"""Make resources globally available.
|
|
323
|
+
|
|
324
|
+
If True, then the resources inferred from the nodes will be put into all HTML pages.
|
|
325
|
+
(This reflects the "default" MkDocs mechanism of putting extra CSS / JS into the
|
|
326
|
+
config file)
|
|
327
|
+
If False, then MkNodes will put the CSS / JS only into the pages which need it.
|
|
328
|
+
(the resources will be moved into the appropriate page template blocks)
|
|
329
|
+
"""
|
|
330
|
+
jinja_config: jinjaconfig.JinjaConfig = Field(default_factory=jinjaconfig.JinjaConfig)
|
|
331
|
+
"""Contains the configuration for the Jinja2 Environment.
|
|
332
|
+
|
|
333
|
+
Allows setting up loaders, extensions and the render behavior.
|
|
334
|
+
"""
|
|
326
335
|
docs_dir: DirectoryPath = Field("docs")
|
|
327
336
|
"""Directory containing documentation markdown source files.
|
|
328
337
|
|
|
@@ -386,7 +395,7 @@ class AppConfig(BaseModel):
|
|
|
386
395
|
```
|
|
387
396
|
"""
|
|
388
397
|
|
|
389
|
-
theme: ThemeConfig = Field(
|
|
398
|
+
theme: themeconfig.ThemeConfig = Field(default_factory=themeconfig.ThemeConfig)
|
|
390
399
|
"""The MkDocs theme for the documentation.
|
|
391
400
|
|
|
392
401
|
Can be a string for built-in themes or a theme config dict.
|
|
@@ -465,8 +474,8 @@ class AppConfig(BaseModel):
|
|
|
465
474
|
dev_addr: localhost:8080 # alternate port
|
|
466
475
|
```
|
|
467
476
|
"""
|
|
468
|
-
|
|
469
|
-
extra_css: list[
|
|
477
|
+
# pydantic.FilePath would be nice.. Looses bw compat to old mkdocs filess
|
|
478
|
+
extra_css: list[str] | None = Field(None)
|
|
470
479
|
"""Custom CSS files to include in the documentation.
|
|
471
480
|
|
|
472
481
|
!!! info "Processing"
|
|
@@ -488,7 +497,7 @@ class AppConfig(BaseModel):
|
|
|
488
497
|
```
|
|
489
498
|
"""
|
|
490
499
|
|
|
491
|
-
extra_javascript: list[
|
|
500
|
+
extra_javascript: list[str | ExtraJavascript] | None = Field(None)
|
|
492
501
|
"""Custom JavaScript files to include in the documentation.
|
|
493
502
|
|
|
494
503
|
!!! info "File Types"
|
|
@@ -511,7 +520,7 @@ class AppConfig(BaseModel):
|
|
|
511
520
|
Scripts are loaded after theme JavaScript files
|
|
512
521
|
"""
|
|
513
522
|
|
|
514
|
-
markdown_extensions: list[
|
|
523
|
+
markdown_extensions: list[dict[str, Any]] | None = Field(None)
|
|
515
524
|
"""PyMarkdown extensions and their configurations.
|
|
516
525
|
|
|
517
526
|
!!! info "Default Extensions"
|
|
@@ -571,7 +580,7 @@ class AppConfig(BaseModel):
|
|
|
571
580
|
```
|
|
572
581
|
"""
|
|
573
582
|
|
|
574
|
-
nav: list[
|
|
583
|
+
nav: list[dict[str, Any] | str] | None = Field(None)
|
|
575
584
|
"""Defines the hierarchical structure of the documentation navigation.
|
|
576
585
|
Each item can be a simple path to a file or a section with nested items.
|
|
577
586
|
|
|
@@ -604,27 +613,7 @@ class AppConfig(BaseModel):
|
|
|
604
613
|
```
|
|
605
614
|
"""
|
|
606
615
|
|
|
607
|
-
|
|
608
|
-
"""The language of the documentation as a BCP 47 language tag.
|
|
609
|
-
|
|
610
|
-
Example in mkdocs.yml:
|
|
611
|
-
```yaml
|
|
612
|
-
language: en
|
|
613
|
-
```
|
|
614
|
-
"""
|
|
615
|
-
|
|
616
|
-
locale: str | None = Field(None)
|
|
617
|
-
"""The locale of the documentation.
|
|
618
|
-
|
|
619
|
-
Affects date formats and other regional settings.
|
|
620
|
-
|
|
621
|
-
Example in mkdocs.yml:
|
|
622
|
-
```yaml
|
|
623
|
-
locale: en_US
|
|
624
|
-
```
|
|
625
|
-
"""
|
|
626
|
-
|
|
627
|
-
extra: dict[str, Any] | None = Field(None)
|
|
616
|
+
extra: dict[str, Any] = Field(default_factory=dict)
|
|
628
617
|
"""A mapping/dictionary of custom data that is passed to the template.
|
|
629
618
|
|
|
630
619
|
This allows template authors to require extra configuration that is not
|
|
@@ -641,7 +630,7 @@ class AppConfig(BaseModel):
|
|
|
641
630
|
```
|
|
642
631
|
"""
|
|
643
632
|
|
|
644
|
-
validation:
|
|
633
|
+
validation: validationconfig.ValidationConfig | None = Field(None)
|
|
645
634
|
"""Controls the validation behavior for links, content, and navigation.
|
|
646
635
|
|
|
647
636
|
!!! info "Validation Levels"
|
|
@@ -672,8 +661,8 @@ class AppConfig(BaseModel):
|
|
|
672
661
|
omitted_files: strict
|
|
673
662
|
```
|
|
674
663
|
"""
|
|
675
|
-
|
|
676
|
-
watch: list[
|
|
664
|
+
# DirectoryPath would be nice
|
|
665
|
+
watch: list[str] | None = Field(None)
|
|
677
666
|
"""Additional directories to monitor for changes during development.
|
|
678
667
|
|
|
679
668
|
!!! info "Behavior"
|
|
@@ -713,7 +702,7 @@ class AppConfig(BaseModel):
|
|
|
713
702
|
Patterns are relative to `docs_dir`
|
|
714
703
|
"""
|
|
715
704
|
|
|
716
|
-
not_in_nav: GitIgnorePatterns = Field(
|
|
705
|
+
not_in_nav: GitIgnorePatterns = Field(str)
|
|
717
706
|
"""Patterns for files that should not generate warnings when not in navigation.
|
|
718
707
|
|
|
719
708
|
!!! info "Use Cases"
|
|
@@ -737,26 +726,55 @@ class AppConfig(BaseModel):
|
|
|
737
726
|
- Referenced programmatically
|
|
738
727
|
"""
|
|
739
728
|
|
|
740
|
-
@field_validator("plugins", mode="before")
|
|
729
|
+
@field_validator("plugins", "markdown_extensions", mode="before")
|
|
741
730
|
@classmethod
|
|
742
731
|
def convert_to_plugin_dict_list(
|
|
743
732
|
cls,
|
|
744
733
|
value: list[str | dict[str, dict[str, Any]]] | dict[str, Any],
|
|
734
|
+
info: ValidationInfo,
|
|
745
735
|
) -> list[dict[str, dict[str, Any]]]:
|
|
746
736
|
result: list[dict[str, Any]] = []
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
737
|
+
match value:
|
|
738
|
+
case dict():
|
|
739
|
+
# Convert dict to list of single-key dicts
|
|
740
|
+
for k, v in value.items():
|
|
741
|
+
result.append({k: v})
|
|
742
|
+
case list():
|
|
743
|
+
for item in value:
|
|
744
|
+
match item:
|
|
745
|
+
case str():
|
|
746
|
+
result.append({item: {}})
|
|
747
|
+
case dict():
|
|
748
|
+
if len(item) > 1:
|
|
749
|
+
f = info.field_name
|
|
750
|
+
msg = f"{f} dictionaries must have a single key"
|
|
751
|
+
raise ValueError(msg)
|
|
752
|
+
result.append(item)
|
|
753
|
+
case _:
|
|
754
|
+
type_str = f"{item!r} ({type(item)})"
|
|
755
|
+
f = info.field_name
|
|
756
|
+
msg = f"Invalid type for {f} section: {type_str}"
|
|
757
|
+
raise ValueError(msg)
|
|
758
758
|
return result
|
|
759
759
|
|
|
760
|
+
@field_validator("extra_javascript", mode="before")
|
|
761
|
+
@classmethod
|
|
762
|
+
def validate_extra_javascript(
|
|
763
|
+
cls, values: list[dict[str, Any] | str]
|
|
764
|
+
) -> list[ExtraJavascript | str]:
|
|
765
|
+
items: list[ExtraJavascript | str] = []
|
|
766
|
+
for value in values:
|
|
767
|
+
if isinstance(value, str):
|
|
768
|
+
if value.endswith(".mjs"):
|
|
769
|
+
item = ExtraJavascript(path=value, type="module")
|
|
770
|
+
items.append(item)
|
|
771
|
+
continue
|
|
772
|
+
items.append(value)
|
|
773
|
+
continue
|
|
774
|
+
item = ExtraJavascript(**value)
|
|
775
|
+
items.append(item)
|
|
776
|
+
return items
|
|
777
|
+
|
|
760
778
|
@field_validator("dev_addr", mode="before")
|
|
761
779
|
@classmethod
|
|
762
780
|
def validate_ip_port(cls, v: str) -> str:
|
|
@@ -771,15 +789,46 @@ class AppConfig(BaseModel):
|
|
|
771
789
|
raise ValueError(msg)
|
|
772
790
|
return v
|
|
773
791
|
|
|
792
|
+
def get_builder(self) -> Callable[..., Any]:
|
|
793
|
+
build_fn = classhelpers.to_callable(self.build_fn)
|
|
794
|
+
build_kwargs = self.build_fn_arguments or {}
|
|
795
|
+
return functools.partial(build_fn, **build_kwargs)
|
|
796
|
+
|
|
797
|
+
def set_theme(
|
|
798
|
+
self,
|
|
799
|
+
theme: str | dict[str, Any] | themeconfig.ThemeConfig,
|
|
800
|
+
**kwargs: Any,
|
|
801
|
+
):
|
|
802
|
+
match theme:
|
|
803
|
+
case themeconfig.ThemeConfig():
|
|
804
|
+
self.theme = theme
|
|
805
|
+
case dict():
|
|
806
|
+
self.theme = themeconfig.ThemeConfig(**{**theme, **kwargs})
|
|
807
|
+
case str():
|
|
808
|
+
self.theme = themeconfig.ThemeConfig(name=theme, **kwargs)
|
|
809
|
+
|
|
810
|
+
# @field_validator("theme", mode="before")
|
|
811
|
+
# @classmethod
|
|
812
|
+
# def validate_theme(cls, value: Any) -> ThemeConfig:
|
|
813
|
+
# if isinstance(value, dict):
|
|
814
|
+
# return themeconfig.ThemeConfig(**value)
|
|
815
|
+
# if isinstance(value, themeconfig.ThemeConfig):
|
|
816
|
+
# return value
|
|
817
|
+
# raise ValueError("Address must be either a dict or Address instance")
|
|
774
818
|
|
|
775
|
-
if __name__ == "__main__":
|
|
776
|
-
import pathlib
|
|
777
819
|
|
|
820
|
+
if __name__ == "__main__":
|
|
778
821
|
import devtools
|
|
779
|
-
import yaml
|
|
780
|
-
|
|
781
|
-
text = pathlib.Path("mkdocs.yml").read_text("utf-8")
|
|
782
|
-
cfg = yaml.unsafe_load(text)
|
|
783
|
-
config = AppConfig(**cfg)
|
|
784
822
|
|
|
785
|
-
|
|
823
|
+
tests = [
|
|
824
|
+
"https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/mkdocs.yml",
|
|
825
|
+
# "https://raw.githubusercontent.com/fastapi-users/fastapi-users/master/mkdocs.yml",
|
|
826
|
+
# "https://raw.githubusercontent.com/pydantic/pydantic/main/mkdocs.yml",
|
|
827
|
+
# "https://raw.githubusercontent.com/facelessuser/pymdown-extensions/refs/heads/main/mkdocs.yml",
|
|
828
|
+
]
|
|
829
|
+
for url in tests:
|
|
830
|
+
config = AppConfig.from_yaml_file(url)
|
|
831
|
+
config.theme = dict(name="xyz", override_dir="overrides")
|
|
832
|
+
|
|
833
|
+
devtools.debug(config.theme)
|
|
834
|
+
print(config.theme, type(config.theme))
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import jinjarope
|
|
4
|
+
from pydantic import BaseModel, Field
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class JinjaConfig(BaseModel):
|
|
8
|
+
jinja_block_start_string: str | None = None
|
|
9
|
+
"""Jinja block start string."""
|
|
10
|
+
jinja_block_end_string: str | None = None
|
|
11
|
+
"""Jinja block end string."""
|
|
12
|
+
jinja_variable_start_string: str | None = None
|
|
13
|
+
"""Jinja variable start string."""
|
|
14
|
+
jinja_variable_end_string: str | None = None
|
|
15
|
+
"""Jinja variable end string."""
|
|
16
|
+
jinja_on_undefined: str = Field("strict")
|
|
17
|
+
"""Jinja undefined macro behavior."""
|
|
18
|
+
jinja_loaders: list[JinjaLoader] | None = None
|
|
19
|
+
"""List containing additional jinja loaders to use.
|
|
20
|
+
|
|
21
|
+
Dictionaries must have the `type` key set to either "filesystem" or "fsspec".
|
|
22
|
+
|
|
23
|
+
Examples:
|
|
24
|
+
``` yaml
|
|
25
|
+
plugins:
|
|
26
|
+
- mknodes:
|
|
27
|
+
jinja_loaders:
|
|
28
|
+
- type: fsspec
|
|
29
|
+
path: github://
|
|
30
|
+
repo: mknodes
|
|
31
|
+
org: phil65
|
|
32
|
+
```
|
|
33
|
+
"""
|
|
34
|
+
jinja_extensions: list[str] | None = None
|
|
35
|
+
"""List containing additional jinja extensions to use.
|
|
36
|
+
|
|
37
|
+
Examples:
|
|
38
|
+
``` yaml
|
|
39
|
+
plugins:
|
|
40
|
+
- mknodes:
|
|
41
|
+
jinja_extensions:
|
|
42
|
+
- jinja2_ansible_filters.AnsibleCoreFiltersExtension
|
|
43
|
+
```
|
|
44
|
+
"""
|
|
45
|
+
|
|
46
|
+
def get_jinja_config(self) -> jinjarope.EnvConfig:
|
|
47
|
+
return jinjarope.EnvConfig(
|
|
48
|
+
block_start_string=self.jinja_block_start_string or "{%",
|
|
49
|
+
block_end_string=self.jinja_block_end_string or "%}",
|
|
50
|
+
variable_start_string=self.jinja_variable_start_string or r"{{",
|
|
51
|
+
variable_end_string=self.jinja_variable_end_string or r"}}",
|
|
52
|
+
# undefined=self.jinja_on_undefined,
|
|
53
|
+
loader=jinjarope.loaders.from_json(self.jinja_loaders),
|
|
54
|
+
extensions=self.jinja_extensions or [],
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class JinjaLoader(BaseModel):
|
|
59
|
+
typ: str
|
|
60
|
+
path: str
|