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.
Files changed (77) hide show
  1. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.pre-commit-config.yaml +2 -2
  2. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/PKG-INFO +2 -3
  3. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/__init__.py +1 -1
  4. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/appconfig/appconfig.py +208 -159
  5. mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/jinjaconfig.py +60 -0
  6. mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/themeconfig.py +179 -0
  7. mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/upathtype.py +178 -0
  8. mkdocs_mknodes-0.6.2/mkdocs_mknodes/appconfig/validationconfig.py +41 -0
  9. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/cli/__init__.py +15 -14
  10. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/build_page.py +4 -3
  11. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/liveserver.py +9 -27
  12. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/use_cases_section.py +3 -4
  13. mkdocs_mknodes-0.6.2/mkdocs_mknodes/plugin/mknodesconfig.py +339 -0
  14. mkdocs_mknodes-0.6.2/mkdocs_mknodes/resources/mkdocs_basic.yml +14 -0
  15. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/pyproject.toml +2 -0
  16. mkdocs_mknodes-0.5.4/mkdocs_mknodes/mknodesconfig.py +0 -106
  17. mkdocs_mknodes-0.5.4/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -35
  18. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.editorconfig +0 -0
  19. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/README.md +0 -0
  20. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/copilot-instructions.md +0 -0
  21. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/dependabot.yml +0 -0
  22. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/workflows/build.yml +0 -0
  23. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.github/workflows/documentation.yml +0 -0
  24. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/.gitignore +0 -0
  25. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/LICENSE +0 -0
  26. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/README.md +0 -0
  27. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/configs/mkdocs_mkdocs.yml +0 -0
  28. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/configs/mkdocs_shared.yml +0 -0
  29. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/assets/cli.gif +0 -0
  30. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/build_process.jinja +0 -0
  31. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/cli_index.jinja +0 -0
  32. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/github_index.jinja +0 -0
  33. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/index.jinja +0 -0
  34. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/plugin_configuration.jinja +0 -0
  35. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/use_case_by_config.jinja +0 -0
  36. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/use_case_default_website.jinja +0 -0
  37. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/use_cases_index.jinja +0 -0
  38. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/docs/why_should_i_use_mknodes.jinja +0 -0
  39. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/duties.py +0 -0
  40. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs.yml +0 -0
  41. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/appconfig/__init__.py +0 -0
  42. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/__init__.py +0 -0
  43. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
  44. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
  45. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
  46. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/buildcollector.py +0 -0
  47. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/buildcontext.py +0 -0
  48. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/builders/__init__.py +0 -0
  49. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/builders/configbuilder.py +0 -0
  50. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/cli/richstate.py +0 -0
  51. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/__init__.py +0 -0
  52. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/serve.py +0 -0
  53. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/commands/utils.py +0 -0
  54. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/__init__.py +0 -0
  55. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
  56. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
  57. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/github_index.py +0 -0
  58. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/manual/root.py +0 -0
  59. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
  60. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/mkdocsconfig.py +0 -0
  61. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/paths.py +0 -0
  62. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/__init__.py +0 -0
  63. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +0 -0
  64. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
  65. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/pluginconfig.py +0 -0
  66. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
  67. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/py.typed +0 -0
  68. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
  69. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes/telemetry.py +0 -0
  70. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/mkdocs_mknodes.sublime-project +0 -0
  71. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/overrides/_dummy.txt +0 -0
  72. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/overrides/partials/actions.html +0 -0
  73. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/__init__.py +0 -0
  74. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/conftest.py +0 -0
  75. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/data/objects.inv +0 -0
  76. {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.6.2}/tests/test_build.py +0 -0
  77. {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.1
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.5.4
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,4 +1,4 @@
1
- __version__ = "0.5.4"
1
+ __version__ = "0.6.2"
2
2
 
3
3
 
4
4
  from .mkdefaultwebsite import MkDefaultWebsite
@@ -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
- from typing import Annotated, Any
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 BaseModel, DirectoryPath, Field, FilePath, HttpUrl, field_validator
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
- def validate_gitignore_patterns(patterns: list[str]) -> list[str]:
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 patterns
40
+ return pattern_str
25
41
 
26
42
 
27
43
  GitIgnorePatterns = Annotated[
28
- list[str],
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[FilePath] | None = Field(None)
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[FilePath] | None = Field(None)
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[str | dict[str, Any]] | None = Field(None)
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[NavItem] | None = Field(None)
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
- language: str | None = Field(None)
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: dict[str, Any] | None = Field(None)
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[DirectoryPath] | None = Field(None)
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(default_factory=list)
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
- for item in value:
748
- if isinstance(item, str):
749
- result.append({item: {}})
750
- elif isinstance(item, dict):
751
- if len(item) > 1:
752
- msg = "Plugin dictionaries must have a single key"
753
- raise ValueError(msg)
754
- result.append(item)
755
- else:
756
- msg = f"Invalid type for plugin section: {item!r} ({type(item)})"
757
- raise ValueError(msg) # noqa: TRY004
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
- devtools.debug(config)
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