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.
- mkdocs_mknodes-0.5.2/.github/copilot-instructions.md +20 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.gitignore +6 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/PKG-INFO +2 -2
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs.yml +10 -2
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/__init__.py +1 -1
- mkdocs_mknodes-0.5.2/mkdocs_mknodes/appconfig/appconfig.py +241 -0
- mkdocs_mknodes-0.5.2/mkdocs_mknodes/builders/configbuilder.py +52 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/cli/__init__.py +3 -2
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/commands/build_page.py +39 -91
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/commands/serve.py +16 -15
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/commands/utils.py +54 -0
- mkdocs_mknodes-0.5.2/mkdocs_mknodes/liveserver.py +397 -0
- mkdocs_mknodes-0.5.2/mkdocs_mknodes/py.typed +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/pyproject.toml +3 -1
- mkdocs_mknodes-0.5.2/tests/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/test_build.py +2 -1
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/test_cli.py +6 -1
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.editorconfig +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/README.md +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/dependabot.yml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/workflows/build.yml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.github/workflows/documentation.yml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/.pre-commit-config.yaml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/LICENSE +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/README.md +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/configs/mkdocs_mkdocs.yml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/configs/mkdocs_shared.yml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/assets/cli.gif +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/build_process.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/cli_index.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/github_index.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/index.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/plugin_configuration.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/use_case_by_config.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/use_case_default_website.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/use_cases_index.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/docs/why_should_i_use_mknodes.jinja +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/duties.py +0 -0
- {mkdocs_mknodes-0.5.0/mkdocs_mknodes/commands → mkdocs_mknodes-0.5.2/mkdocs_mknodes/appconfig}/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/buildcollector.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/buildcontext.py +0 -0
- {mkdocs_mknodes-0.5.0/tests → mkdocs_mknodes-0.5.2/mkdocs_mknodes/builders}/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/cli/richstate.py +0 -0
- /mkdocs_mknodes-0.5.0/mkdocs_mknodes/py.typed → /mkdocs_mknodes-0.5.2/mkdocs_mknodes/commands/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/github_index.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/root.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/manual/use_cases_section.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/mkdocsconfig.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/mknodesconfig.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/paths.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/__init__.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/pluginconfig.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes/telemetry.py +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/mkdocs_mknodes.sublime-project +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/overrides/_dummy.txt +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/overrides/partials/actions.html +0 -0
- {mkdocs_mknodes-0.5.0 → mkdocs_mknodes-0.5.2}/tests/conftest.py +0 -0
- {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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: mkdocs-mknodes
|
|
3
|
-
Version: 0.5.
|
|
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
|
|
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
|
-
|
|
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
|
|
@@ -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
|
|
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 =
|
|
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
|
|
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
|
-
|
|
58
|
-
config_path:
|
|
59
|
-
repo_path:
|
|
60
|
-
build_fn:
|
|
61
|
-
site_dir:
|
|
62
|
-
clone_depth:
|
|
63
|
-
kwargs:
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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:
|
|
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 =
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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
|
|
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:
|
|
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())
|