mkdocs-mknodes 0.5.0__tar.gz → 0.5.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 (71) hide show
  1. mkdocs_mknodes-0.5.2/.github/copilot-instructions.md +20 -0
  2. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.gitignore +6 -0
  3. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/PKG-INFO +2 -2
  4. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs.yml +10 -2
  5. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/__init__.py +1 -1
  6. mkdocs_mknodes-0.5.2/mkdocs_mknodes/appconfig/appconfig.py +241 -0
  7. mkdocs_mknodes-0.5.2/mkdocs_mknodes/builders/configbuilder.py +52 -0
  8. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/cli/__init__.py +3 -2
  9. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/commands/build_page.py +39 -91
  10. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/commands/serve.py +16 -15
  11. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/commands/utils.py +54 -0
  12. mkdocs_mknodes-0.5.2/mkdocs_mknodes/liveserver.py +397 -0
  13. mkdocs_mknodes-0.5.2/mkdocs_mknodes/py.typed +0 -0
  14. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/pyproject.toml +3 -1
  15. mkdocs_mknodes-0.5.2/tests/__init__.py +0 -0
  16. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/test_build.py +2 -1
  17. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/test_cli.py +6 -1
  18. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.editorconfig +0 -0
  19. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/README.md +0 -0
  20. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/dependabot.yml +0 -0
  21. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/workflows/build.yml +0 -0
  22. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/workflows/documentation.yml +0 -0
  23. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.pre-commit-config.yaml +0 -0
  24. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/LICENSE +0 -0
  25. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/README.md +0 -0
  26. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/configs/mkdocs_mkdocs.yml +0 -0
  27. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/configs/mkdocs_shared.yml +0 -0
  28. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/assets/cli.gif +0 -0
  29. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/build_process.jinja +0 -0
  30. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/cli_index.jinja +0 -0
  31. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/github_index.jinja +0 -0
  32. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/index.jinja +0 -0
  33. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/plugin_configuration.jinja +0 -0
  34. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/use_case_by_config.jinja +0 -0
  35. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/use_case_default_website.jinja +0 -0
  36. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/use_cases_index.jinja +0 -0
  37. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/why_should_i_use_mknodes.jinja +0 -0
  38. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/duties.py +0 -0
  39. {mkdocs_mknodes-0.5.0/mkdocs_mknodes/commands → mkdocs_mknodes-0.5.2/mkdocs_mknodes/appconfig}/__init__.py +0 -0
  40. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/__init__.py +0 -0
  41. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
  42. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
  43. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
  44. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/buildcollector.py +0 -0
  45. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/buildcontext.py +0 -0
  46. {mkdocs_mknodes-0.5.0/tests → mkdocs_mknodes-0.5.2/mkdocs_mknodes/builders}/__init__.py +0 -0
  47. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/cli/richstate.py +0 -0
  48. /mkdocs_mknodes-0.5.0/mkdocs_mknodes/py.typed → /mkdocs_mknodes-0.5.2/mkdocs_mknodes/commands/__init__.py +0 -0
  49. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/__init__.py +0 -0
  50. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
  51. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
  52. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/github_index.py +0 -0
  53. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/root.py +0 -0
  54. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/use_cases_section.py +0 -0
  55. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
  56. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/mkdocsconfig.py +0 -0
  57. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/mknodesconfig.py +0 -0
  58. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/paths.py +0 -0
  59. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/__init__.py +0 -0
  60. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +0 -0
  61. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
  62. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/pluginconfig.py +0 -0
  63. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
  64. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -0
  65. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
  66. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/telemetry.py +0 -0
  67. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes.sublime-project +0 -0
  68. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/overrides/_dummy.txt +0 -0
  69. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/overrides/partials/actions.html +0 -0
  70. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/conftest.py +0 -0
  71. {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/data/objects.inv +0 -0
@@ -0,0 +1,20 @@
1
+ ## Code style
2
+
3
+ You can assume Python 3.12.
4
+ Use newest language features if possible
5
+ Adhere to pep8.
6
+ Consider using pattern matching and walrus operators.
7
+
8
+ ## Tests
9
+
10
+ Tests are written using PyTest.
11
+
12
+
13
+ ## DocStrings
14
+
15
+ DocStrings are written in google-style.
16
+ Dont add the types to the Args section.
17
+ Only add a Return section if a value is returned and the meaning of the returned value
18
+ is not obvious.
19
+ You can use markdown admonitions with python-markdown syntax (!!! info, !!! note, !!! warning)
20
+ You can use markdown tables and markdown lists if neccessary.
@@ -41,8 +41,14 @@ ENV/
41
41
  # .vscode
42
42
  .vscode/
43
43
 
44
+ # aider
45
+ .aider
46
+
44
47
  # PyCharm
45
48
  .idea/
46
49
 
47
50
  # OS files
48
51
  .DS_Store
52
+
53
+ # uv
54
+ uv.lock
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: mkdocs-mknodes
3
- Version: 0.5.0
3
+ Version: 0.5.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
@@ -24,7 +24,7 @@ Classifier: Topic :: Software Development :: User Interfaces
24
24
  Classifier: Topic :: Text Processing :: Markup :: Markdown
25
25
  Requires-Python: >=3.12
26
26
  Requires-Dist: jinja2
27
- Requires-Dist: jinjarope
27
+ Requires-Dist: jinjarope[yaml]
28
28
  Requires-Dist: logfire[aiohttp,requests,system-metrics]
29
29
  Requires-Dist: mkdocs>=1.5
30
30
  Requires-Dist: mknodes
@@ -11,6 +11,12 @@ theme:
11
11
  icon:
12
12
  logo: material/graph-outline
13
13
  palette:
14
+ # Palette toggle for automatic mode
15
+ - media: "(prefers-color-scheme)"
16
+ toggle:
17
+ icon: material/brightness-auto
18
+ name: Switch to light mode
19
+
14
20
  # Palette toggle for light mode
15
21
  - media: "(prefers-color-scheme: light)"
16
22
  scheme: default
@@ -25,14 +31,14 @@ theme:
25
31
  primary: custom
26
32
  toggle:
27
33
  icon: material/brightness-4
28
- name: Switch to light mode
34
+ name: Switch to system preference
29
35
  features:
30
36
  - announce.dismiss
31
37
  - content.action.edit
32
38
  - content.code.copy
33
39
  - content.code.select
34
40
  - content.code.annotate
35
- # - content.tooltips # for insiders..
41
+ - content.tooltips
36
42
  # - content.tabs.link
37
43
  - navigation.tracking # update URL based on current item in TOC
38
44
  - navigation.path # shows breadcrumbs
@@ -66,6 +72,8 @@ plugins:
66
72
  options:
67
73
  extensions:
68
74
  - griffe_fieldz: { include_inherited: true }
75
+ # - griffe_pydantic:
76
+ # schema: true
69
77
  # https://mkdocstrings.github.io/python/usage/
70
78
  show_signature_annotations: true
71
79
  show_symbol_type_toc: true
@@ -1,4 +1,4 @@
1
- __version__ = "0.5.0"
1
+ __version__ = "0.5.2"
2
2
 
3
3
 
4
4
  from .mkdefaultwebsite import MkDefaultWebsite
@@ -0,0 +1,241 @@
1
+ from __future__ import annotations
2
+
3
+ import ipaddress
4
+ from typing import Annotated, Any
5
+
6
+ from pathspec import gitignore
7
+ from pydantic import BaseModel, DirectoryPath, Field, FilePath, HttpUrl, field_validator
8
+ from pydantic.functional_validators import BeforeValidator
9
+ from pydantic_core import PydanticCustomError
10
+
11
+
12
+ def validate_gitignore_patterns(patterns: list[str]) -> list[str]:
13
+ """Validate a list of gitignore patterns using pathspec."""
14
+ try:
15
+ gitignore.GitIgnoreSpec.from_lines(patterns)
16
+ except Exception as e:
17
+ msg = "invalid_gitignore_pattern"
18
+ raise PydanticCustomError(
19
+ msg,
20
+ "Invalid gitignore pattern(s): {error}",
21
+ {"error": str(e)},
22
+ ) from e
23
+ else:
24
+ return patterns
25
+
26
+
27
+ GitIgnorePatterns = Annotated[
28
+ list[str],
29
+ BeforeValidator(validate_gitignore_patterns),
30
+ ]
31
+
32
+
33
+ class NavItem(BaseModel):
34
+ """Represents a navigation item in the MkDocs configuration.
35
+
36
+ Can be a string (for a simple link) or a dict (for nested navigation).
37
+ """
38
+
39
+ item: str | dict[str, NavItem]
40
+
41
+
42
+ class ThemeConfig(BaseModel):
43
+ """Configuration for the MkDocs theme."""
44
+
45
+ class Config:
46
+ extra = "allow"
47
+ populate_by_name = True
48
+
49
+ name: str = Field(..., description="The name of the theme to use.")
50
+ custom_dir: DirectoryPath | None = Field(
51
+ None, description="Directory containing a custom theme."
52
+ )
53
+ static_templates: list[str] | None = Field(
54
+ None, description="List of templates to render as static pages."
55
+ )
56
+ locale: str | None = Field(
57
+ None, description="The locale to use for the theme (e.g., 'en' or 'fr')."
58
+ )
59
+ # Material-related
60
+ # palette: dict[str, Any] | None = Field(
61
+ # None, description="Color palette configuration for the theme."
62
+ # )
63
+ # font: dict[str, Any] | None = Field(
64
+ # None, description="Font configuration for the theme."
65
+ # )
66
+ # features: list[str] | None = Field(
67
+ # None, description="List of theme-specific features to enable."
68
+ # )
69
+ # logo: str | None = Field(None, description="Path to a logo file for the theme.")
70
+ # icon: str | None = Field(None, description="Path to a favicon file.")
71
+ # favicon: str | None = Field(None, description="Path to a favicon file.")
72
+ # language: str | None = Field(None, description="Language for theme localization.")
73
+
74
+
75
+ class PluginConfig(BaseModel):
76
+ """Configuration for a MkDocs plugin."""
77
+
78
+ name: str = Field(..., description="The name of the plugin.")
79
+ config: dict[str, Any] | None = Field(
80
+ None, description="Plugin-specific configuration options."
81
+ )
82
+
83
+
84
+ class AppConfig(BaseModel):
85
+ """Represents the full configuration for a MkDocs project."""
86
+
87
+ config_file_path: str | None = Field(None, description="Path to the config file.")
88
+
89
+ # Site information
90
+ site_name: str = Field(..., description="The name of the project documentation.")
91
+ site_url: HttpUrl | None = Field(
92
+ None, description="The URL where the documentation will be hosted."
93
+ )
94
+ site_description: str | None = Field(
95
+ None, description="A description of the documentation project."
96
+ )
97
+ site_author: str | None = Field(None, description="The author of the documentation.")
98
+ copyright: str | None = Field(
99
+ None, description="A copyright statement for the documentation."
100
+ )
101
+
102
+ # Repository information
103
+ repo_name: str | None = Field(None, description="The name of the source repository.")
104
+ repo_url: HttpUrl | None = Field(
105
+ None, description="The URL of the source repository."
106
+ )
107
+ edit_uri: str | None = Field(
108
+ None, description="Path to the docs directory in the source repository."
109
+ )
110
+ remote_branch: str | None = Field(
111
+ None, description="The remote branch to point to (default: 'master')."
112
+ )
113
+ remote_name: str | None = Field(
114
+ None, description="The remote name to push to (default: 'origin')."
115
+ )
116
+
117
+ # Configuration directories
118
+ docs_dir: DirectoryPath = Field(
119
+ "docs", description="The directory containing the documentation source files."
120
+ )
121
+ site_dir: DirectoryPath = Field(
122
+ "site", description="The directory where the output HTML will be created."
123
+ )
124
+ extra_templates: list[DirectoryPath] | None = Field(
125
+ None, description="List of directories containing extra Jinja2 templates."
126
+ )
127
+
128
+ # Theme configuration
129
+ theme: ThemeConfig = Field(
130
+ ..., description="The theme configuration for the documentation."
131
+ )
132
+
133
+ # Build configuration
134
+ use_directory_urls: bool = Field(
135
+ True, description="Use directory URLs when building pages (default: True)."
136
+ )
137
+ strict: bool = Field(
138
+ False, description="Enable strict mode for warnings as errors (default: False)."
139
+ )
140
+ dev_addr: str = Field(
141
+ "127.0.0.1:8000", description="The server address for the development server."
142
+ )
143
+ extra_css: list[FilePath] | None = Field(
144
+ None, description="List of CSS files to include in the documentation."
145
+ )
146
+ extra_javascript: list[FilePath] | None = Field(
147
+ None, description="List of JavaScript files to include in the documentation."
148
+ )
149
+
150
+ # Markdown extensions
151
+ markdown_extensions: list[str | dict[str, Any]] | None = Field(
152
+ None, description="List of Markdown extensions to use."
153
+ )
154
+ hooks: list[str] | None = Field(
155
+ None, description="List of Python scripts to load as hooks."
156
+ )
157
+
158
+ # Navigation
159
+ nav: list[NavItem] | None = Field(
160
+ None, description="The navigation structure for the documentation."
161
+ )
162
+
163
+ # Plugins
164
+ plugins: list[dict[str, Any]] = Field(
165
+ default_factory=list, description="List of plugins to use."
166
+ )
167
+
168
+ # Internationalization
169
+ language: str | None = Field(
170
+ None, description="The language of the documentation (as a BCP 47 language tag)."
171
+ )
172
+ locale: str | None = Field(
173
+ None, description="The locale of the documentation (e.g., 'en_US')."
174
+ )
175
+
176
+ # Additional options
177
+ extra: dict[str, Any] | None = Field(
178
+ None, description="A set of key-value pairs for custom data in templates."
179
+ )
180
+ validation: dict[str, Any] | None = Field(
181
+ None, description="Validation options for external links and fragments."
182
+ )
183
+ watch: list[DirectoryPath] | None = Field(
184
+ None, description="List of directories to watch for changes."
185
+ )
186
+ exclude_docs: GitIgnorePatterns = Field(
187
+ default_factory=list,
188
+ description="Gitignore-like file patterns to exclude pages from the site.",
189
+ )
190
+
191
+ not_in_nav: GitIgnorePatterns = Field(
192
+ default_factory=list,
193
+ description="Gitignore-like file patterns to exclude pages from nav.",
194
+ )
195
+
196
+ @field_validator("plugins", mode="before")
197
+ @classmethod
198
+ def convert_to_plugin_dict_list(
199
+ cls,
200
+ value: list[str | dict[str, dict[str, Any]]] | dict[str, Any],
201
+ ) -> list[dict[str, dict[str, Any]]]:
202
+ result: list[dict[str, Any]] = []
203
+ for item in value:
204
+ if isinstance(item, str):
205
+ result.append({item: {}})
206
+ elif isinstance(item, dict):
207
+ if len(item) > 1:
208
+ msg = "Plugin dictionaries must have a single key"
209
+ raise ValueError(msg)
210
+ result.append(item)
211
+ else:
212
+ msg = f"Invalid type for plugin section: {item!r} ({type(item)})"
213
+ raise ValueError(msg) # noqa: TRY004
214
+ return result
215
+
216
+ @field_validator("dev_addr", mode="before")
217
+ @classmethod
218
+ def validate_ip_port(cls, v: str) -> str:
219
+ try:
220
+ ip, port = v.split(":")
221
+ ipaddress.ip_address(ip) # Validates IP
222
+ except ValueError as e:
223
+ msg = f"Invalid IP:PORT format - {e!s}"
224
+ raise ValueError(msg) from e
225
+ if not 1 <= int(port) <= 65535: # noqa: PLR2004
226
+ msg = "Port must be between 1 and 65535"
227
+ raise ValueError(msg)
228
+ return v
229
+
230
+
231
+ if __name__ == "__main__":
232
+ import pathlib
233
+
234
+ import devtools
235
+ import yaml
236
+
237
+ text = pathlib.Path("mkdocs.yml").read_text()
238
+ cfg = yaml.unsafe_load(text)
239
+ config = AppConfig(**cfg)
240
+
241
+ devtools.debug(config)
@@ -0,0 +1,52 @@
1
+ from __future__ import annotations
2
+
3
+ import io
4
+ import os
5
+ from typing import Any
6
+
7
+ from jinjarope import yamltools
8
+ from mkdocs.config import load_config
9
+ from mkdocs.config.defaults import MkDocsConfig
10
+ from mknodes.info import mkdocsconfigfile
11
+
12
+ from mkdocs_mknodes import telemetry
13
+
14
+
15
+ logger = telemetry.get_plugin_logger(__name__)
16
+
17
+
18
+ class ConfigBuilder:
19
+ def __init__(
20
+ self,
21
+ configs: list[mkdocsconfigfile.MkDocsConfigFile] | None = None,
22
+ repo_path: str | None = ".",
23
+ build_fn: str | None = None,
24
+ clone_depth: int | None = 100,
25
+ ):
26
+ self.configs = configs or []
27
+ self.repo_path = repo_path
28
+ self.build_fn = build_fn
29
+ self.clone_depth = clone_depth
30
+
31
+ def add_config_file(self, path: str | os.PathLike[str]):
32
+ cfg = mkdocsconfigfile.MkDocsConfigFile(path)
33
+ self.configs.append(cfg)
34
+
35
+ def build_mkdocs_config(self, **kwargs: Any) -> MkDocsConfig:
36
+ cfg = self.configs[0]
37
+ cfg = {**cfg, **kwargs}
38
+ text = yamltools.dump_yaml(cfg)
39
+ buffer = io.StringIO(text)
40
+ buffer.name = self.configs[0].path
41
+ config = load_config(buffer, **kwargs)
42
+ for plugin in config["plugins"]:
43
+ if "mknodes" in plugin:
44
+ if self.repo_path is not None:
45
+ plugin["mknodes"]["repo_path"] = self.repo_path
46
+ if self.build_fn is not None:
47
+ plugin["mknodes"]["build_fn"] = self.build_fn
48
+ if self.clone_depth is not None:
49
+ plugin["mknodes"]["clone_depth"] = self.clone_depth
50
+ for k, v in config.items():
51
+ logger.debug("%s: %s", k, v)
52
+ return config
@@ -8,7 +8,8 @@ from mknodes.info.mkdocsconfigfile import MkDocsConfigFile
8
8
 
9
9
  import typer as t
10
10
 
11
- from mknodes.utils import classhelpers, log, yamlhelpers
11
+ from jinjarope import yamltools
12
+ from mknodes.utils import classhelpers, log
12
13
  import mknodes as mk
13
14
 
14
15
  from mkdocs_mknodes import buildcollector, paths
@@ -170,7 +171,7 @@ def create_config(
170
171
  config["site_name"] = info.distribution_name
171
172
  config["site_author"] = info.author_name
172
173
  config["copyright"] = f"Copyright © {datetime.now().year} {info.author_name}"
173
- result = yamlhelpers.dump_yaml(config)
174
+ result = yamltools.dump_yaml(config)
174
175
  print(result)
175
176
 
176
177
 
@@ -4,28 +4,25 @@ from __future__ import annotations
4
4
 
5
5
  from collections.abc import Collection, Sequence
6
6
  from datetime import UTC, datetime
7
- import gzip
8
- import io
9
7
  import os
10
- import pathlib
11
- import re
12
8
  from typing import TYPE_CHECKING, Any
13
9
  from urllib.parse import urljoin, urlsplit
14
10
 
15
11
  import jinja2
16
12
  from jinja2.exceptions import TemplateNotFound
17
- from jinjarope import htmlfilters
13
+ from jinjarope import envtests, htmlfilters
18
14
  import logfire
19
15
  from mkdocs import exceptions
20
16
  from mkdocs.commands import build as mkdocs_build
21
- from mkdocs.config import load_config
22
17
  from mkdocs.structure.files import InclusionLevel
23
18
  from mkdocs.structure.nav import Navigation, get_navigation
24
19
  from mkdocs.structure.pages import Page
25
20
  from mknodes.info import mkdocsconfigfile
26
- from mknodes.utils import pathhelpers, yamlhelpers
21
+ from mknodes.utils import pathhelpers
22
+ import upath
27
23
 
28
24
  from mkdocs_mknodes import telemetry
25
+ from mkdocs_mknodes.builders import configbuilder
29
26
  from mkdocs_mknodes.commands import utils
30
27
 
31
28
 
@@ -48,44 +45,31 @@ def build(
48
45
  config_path: str | os.PathLike[str],
49
46
  repo_path: str,
50
47
  build_fn: str | None,
48
+ *,
51
49
  site_dir: str | None = None,
52
50
  clone_depth: int = 100,
53
51
  **kwargs: Any,
54
52
  ):
55
53
  """Build a MkNodes-based website.
56
54
 
57
- Arguments:
58
- config_path: The path to the config file to use
59
- repo_path: Path to the repository a page should be built for
60
- build_fn: Callable to use for creating the webpage
61
- site_dir: Path for the website build
62
- clone_depth: If repository is remote, the amount of commits to fetch
63
- kwargs: Optional config values (overrides value from config)
55
+ Args:
56
+ config_path: Path to the MkDocs config file
57
+ repo_path: Repository path/URL to build docs for
58
+ build_fn: Fully qualified name of build function to use
59
+ site_dir: Output directory for built site
60
+ clone_depth: Number of commits to fetch for Git repos
61
+ kwargs: Additional config overrides passed to MkDocs
64
62
  """
65
-
66
- def build_config():
67
- cfg = mkdocsconfigfile.MkDocsConfigFile(config_path)
68
- cfg.update_mknodes_section(
69
- repo_url=repo_path,
70
- build_fn=build_fn,
71
- clone_depth=clone_depth,
72
- )
73
- if site_dir:
74
- cfg["site_dir"] = site_dir
75
- text = yamlhelpers.dump_yaml(dict(cfg))
76
- buffer = io.StringIO(text)
77
- buffer.name = config_path
78
- config = load_config(buffer, **kwargs)
79
- for k, v in config.items():
80
- logger.debug("%s: %s", k, v)
81
- return config
82
-
83
- config = build_config()
63
+ cfg_builder = configbuilder.ConfigBuilder(
64
+ repo_path=repo_path, build_fn=build_fn, clone_depth=clone_depth
65
+ )
66
+ cfg_builder.add_config_file(config_path)
67
+ config = cfg_builder.build_mkdocs_config(site_dir=site_dir, **kwargs)
84
68
  with logfire.span("plugins callback: on_startup", config=config):
85
- config.plugins.run_event("startup", command="build", dirty=False)
69
+ config.plugins.on_startup(command="build", dirty=False)
86
70
  _build(config)
87
71
  with logfire.span("plugins callback: shutdown", config=config):
88
- config.plugins.run_event("shutdown")
72
+ config.plugins.on_shutdown()
89
73
 
90
74
 
91
75
  @utils.handle_exceptions
@@ -105,9 +89,6 @@ def _build(
105
89
  live_server_url: An optional URL of the live server to use
106
90
  dirty: Do a dirty build
107
91
  """
108
- inclusion = (
109
- InclusionLevel.is_in_serve if live_server_url else InclusionLevel.is_included
110
- )
111
92
  with logfire.span("plugins callback: on_config", config=config):
112
93
  config = config.plugins.on_config(config)
113
94
  with logfire.span("plugins callback: on_pre_build", config=config):
@@ -120,7 +101,7 @@ def _build(
120
101
  logger.warning("A 'dirty' build is being performed (for site dev purposes only)")
121
102
  if not live_server_url: # pragma: no cover
122
103
  logger.info("Building documentation to directory: %s", config.site_dir)
123
- if dirty and contains_files(config.site_dir):
104
+ if dirty and envtests.contains_files(config.site_dir):
124
105
  logger.info("The directory contains stale files. Use --clean to remove them.")
125
106
  # First gather all data from all files/pages to ensure all data is
126
107
  # consistent across all pages.
@@ -137,6 +118,9 @@ def _build(
137
118
  nav = config.plugins.on_nav(nav, config=config, files=files)
138
119
  logger.debug("Reading markdown pages.")
139
120
  excluded: list[str] = []
121
+ inclusion = (
122
+ InclusionLevel.is_in_serve if live_server_url else InclusionLevel.is_included
123
+ )
140
124
  with logfire.span("populate pages"):
141
125
  for file in files.documentation_pages(inclusion=inclusion):
142
126
  with logfire.span(f"populate page for {file.src_uri}", file=file):
@@ -280,16 +264,6 @@ def _build_page(
280
264
  config._current_page = None
281
265
 
282
266
 
283
- def contains_files(folder: str | os.PathLike[str]) -> bool:
284
- """Check if given path exists and contains any files or folders.
285
-
286
- Args:
287
- folder: The folder to check
288
- """
289
- path = pathlib.Path(folder)
290
- return path.exists() and any(path.iterdir())
291
-
292
-
293
267
  def _build_template(
294
268
  name: str,
295
269
  template: jinja2.Template,
@@ -298,12 +272,10 @@ def _build_template(
298
272
  nav: Navigation,
299
273
  ) -> str:
300
274
  """Return rendered output for given template as a string."""
301
- # Run `pre_template` plugin events.
302
275
  template = config.plugins.on_pre_template(template, template_name=name, config=config)
303
276
 
304
- if is_error_template(name):
305
- # Force absolute URLs in the nav of error pages and account for the
306
- # possibility that the docs root might be different than the server root.
277
+ if utils.is_error_template(name):
278
+ # Force absolute URLs for error pages. Docs root & server root might differ.
307
279
  # See https://github.com/mkdocs/mkdocs/issues/77.
308
280
  # However, if site_url is not set, assume the docs root and server root
309
281
  # are the same. See https://github.com/mkdocs/mkdocs/issues/1598.
@@ -311,10 +283,8 @@ def _build_template(
311
283
  else:
312
284
  base_url = htmlfilters.relative_url_mkdocs(".", name)
313
285
  context = mkdocs_build.get_context(nav, files, config, base_url=base_url)
314
- # Run `template_context` plugin events.
315
286
  ctx = config.plugins.on_template_context(context, template_name=name, config=config)
316
287
  output = template.render(ctx)
317
- # Run `post_template` plugin events.
318
288
  return config.plugins.on_post_template(output, template_name=name, config=config)
319
289
 
320
290
 
@@ -331,27 +301,20 @@ def _build_theme_template(
331
301
  try:
332
302
  template = env.get_template(template_name)
333
303
  except TemplateNotFound:
334
- logger.warning("Template skipped: '%s' not found in theme dirs.", template_name)
304
+ logger.warning("Template skipped: %r not found in theme dirs.", template_name)
335
305
  return
336
306
 
337
307
  output = _build_template(template_name, template, files, config, nav)
338
308
 
339
309
  if output.strip():
340
- output_path = pathlib.Path(config.site_dir) / template_name
310
+ output_path = upath.UPath(config.site_dir) / template_name
341
311
  pathhelpers.write_file(output.encode(), output_path)
342
-
343
312
  if template_name == "sitemap.xml":
344
- logger.debug("Gzipping template: %s", template_name)
345
- gz_filename = pathlib.Path(f"{output_path}.gz")
346
313
  docs = files.documentation_pages()
347
314
  ts = get_build_timestamp(pages=[f.page for f in docs if f.page is not None])
348
- with (
349
- gz_filename.open("wb") as f,
350
- gzip.GzipFile(gz_filename, fileobj=f, mode="wb", mtime=ts) as gz_buf,
351
- ):
352
- gz_buf.write(output.encode())
315
+ utils.write_gzip(f"{output_path}.gz", output, timestamp=ts)
353
316
  else:
354
- logger.info("Template skipped: '%s' generated empty output.", template_name)
317
+ logger.info("Template skipped: %r generated empty output.", template_name)
355
318
 
356
319
 
357
320
  def _build_extra_template(
@@ -362,18 +325,18 @@ def _build_extra_template(
362
325
 
363
326
  file = files.get_file_from_path(template_name)
364
327
  if file is None:
365
- logger.warning("Template skipped: '%s' not found in docs_dir.", template_name)
328
+ logger.warning("Template skipped: %r not found in docs_dir.", template_name)
366
329
  return
367
330
  try:
368
331
  template = jinja2.Template(file.content_string)
369
332
  except Exception as e: # noqa: BLE001
370
- logger.warning("Error reading template '%s': %s", template_name, e)
333
+ logger.warning("Error reading template %r: %s", template_name, e)
371
334
  return
372
335
  output = _build_template(template_name, template, files, config, nav)
373
336
  if output.strip():
374
337
  pathhelpers.write_file(output.encode(), file.abs_dest_path)
375
338
  else:
376
- logger.info("Template skipped: '%s' generated empty output.", template_name)
339
+ logger.info("Template skipped: %r generated empty output.", template_name)
377
340
 
378
341
 
379
342
  def get_build_timestamp(*, pages: Collection[Page] | None = None) -> int:
@@ -381,37 +344,22 @@ def get_build_timestamp(*, pages: Collection[Page] | None = None) -> int:
381
344
 
382
345
  In reality this is just today's date because that's how pages' update time
383
346
  is populated.
347
+
348
+ Args:
349
+ pages: Optional collection of pages to determine timestamp from
350
+
351
+ Returns:
352
+ Unix timestamp as integer
384
353
  """
385
354
  if pages:
386
355
  # Lexicographic comparison is OK for ISO date.
387
356
  date_string = max(p.update_date for p in pages)
388
357
  dt = datetime.fromisoformat(date_string).replace(tzinfo=UTC)
389
358
  else:
390
- dt = get_build_datetime()
359
+ dt = utils.get_build_datetime()
391
360
  return int(dt.timestamp())
392
361
 
393
362
 
394
- def get_build_datetime() -> datetime:
395
- """Returns an aware datetime object.
396
-
397
- Support SOURCE_DATE_EPOCH environment variable for reproducible builds.
398
- See https://reproducible-builds.org/specs/source-date-epoch/
399
- """
400
- source_date_epoch = os.environ.get("SOURCE_DATE_EPOCH")
401
- if source_date_epoch is None:
402
- return datetime.now(UTC)
403
-
404
- return datetime.fromtimestamp(int(source_date_epoch), UTC)
405
-
406
-
407
- _ERROR_TEMPLATE_RE = re.compile(r"^\d{3}\.html?$")
408
-
409
-
410
- def is_error_template(path: str) -> bool:
411
- """Return True if the given file path is an HTTP error template."""
412
- return bool(_ERROR_TEMPLATE_RE.match(path))
413
-
414
-
415
363
  if __name__ == "__main__":
416
364
  config = mkdocsconfigfile.MkDocsConfigFile("mkdocs.yml")
417
365
  print(config.dump_config())