mkdocs-mknodes 0.5.4__tar.gz → 0.7.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.7.2/.github/workflows/documentation.yml +68 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.pre-commit-config.yaml +2 -2
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/PKG-INFO +2 -3
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/__init__.py +1 -1
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/appconfig.py +202 -161
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/base.py +64 -0
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/jinjaconfig.py +60 -0
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/themeconfig.py +179 -0
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/upathtype.py +178 -0
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/validationconfig.py +41 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/builders/configbuilder.py +3 -4
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/cli/__init__.py +15 -14
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/build_page.py +73 -19
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/serve.py +12 -8
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/utils.py +5 -5
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/liveserver.py +9 -27
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/use_cases_section.py +3 -4
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/mkdocsconfig.py +5 -15
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/__init__.py +13 -5
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +8 -3
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/plugin/mknodesconfig.py +342 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/pluginconfig.py +2 -1
- mkdocs_mknodes-0.7.2/mkdocs_mknodes/resources/mkdocs_basic.yml +14 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/pyproject.toml +2 -0
- mkdocs_mknodes-0.5.4/.github/workflows/documentation.yml +0 -68
- 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.7.2}/.editorconfig +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/README.md +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/copilot-instructions.md +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/dependabot.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.github/workflows/build.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/.gitignore +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/LICENSE +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/README.md +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/configs/mkdocs_mkdocs.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/configs/mkdocs_shared.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/assets/cli.gif +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/build_process.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/cli_index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/github_index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/plugin_configuration.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/use_case_by_config.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/use_case_default_website.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/use_cases_index.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/docs/why_should_i_use_mknodes.jinja +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/duties.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs.yml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/buildcollector.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/buildcontext.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/builders/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/cli/richstate.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/github_index.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/root.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/paths.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/py.typed +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/telemetry.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes.sublime-project +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/overrides/_dummy.txt +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/overrides/partials/actions.html +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/__init__.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/conftest.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/data/objects.inv +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/test_build.py +0 -0
- {mkdocs_mknodes-0.5.4 → mkdocs_mknodes-0.7.2}/tests/test_cli.py +0 -0
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
name: Build documentation
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- main
|
|
7
|
+
|
|
8
|
+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
|
|
9
|
+
permissions:
|
|
10
|
+
contents: read
|
|
11
|
+
pages: write
|
|
12
|
+
id-token: write
|
|
13
|
+
|
|
14
|
+
# Allow one concurrent deployment
|
|
15
|
+
concurrency:
|
|
16
|
+
group: "pages"
|
|
17
|
+
cancel-in-progress: true
|
|
18
|
+
|
|
19
|
+
# Default to bash
|
|
20
|
+
defaults:
|
|
21
|
+
run:
|
|
22
|
+
shell: bash
|
|
23
|
+
|
|
24
|
+
jobs:
|
|
25
|
+
build:
|
|
26
|
+
runs-on: ubuntu-latest
|
|
27
|
+
|
|
28
|
+
steps:
|
|
29
|
+
- name: Check out repository
|
|
30
|
+
uses: actions/checkout@v4
|
|
31
|
+
with:
|
|
32
|
+
fetch-depth: 0
|
|
33
|
+
|
|
34
|
+
- name: Set up Python 3.12
|
|
35
|
+
uses: actions/setup-python@v5
|
|
36
|
+
with:
|
|
37
|
+
python-version: "3.12"
|
|
38
|
+
|
|
39
|
+
- name: Setup Graphviz
|
|
40
|
+
uses: ts-graphviz/setup-graphviz@v2
|
|
41
|
+
|
|
42
|
+
- name: Install uv
|
|
43
|
+
uses: yezz123/setup-uv@v4
|
|
44
|
+
|
|
45
|
+
- name: Install dependencies
|
|
46
|
+
run: uv sync --all-extras
|
|
47
|
+
|
|
48
|
+
- name: Build main documentation page
|
|
49
|
+
run: uv run mknodes build -v
|
|
50
|
+
|
|
51
|
+
- name: Build example sub-page (MkDocs)
|
|
52
|
+
run: uv run mknodes build -d ../site/mkdocs -p configs/mkdocs_mkdocs.yml -v --clone-depth 100
|
|
53
|
+
|
|
54
|
+
- name: Package and upload page artifact
|
|
55
|
+
uses: actions/upload-pages-artifact@v3
|
|
56
|
+
with:
|
|
57
|
+
path: ./site
|
|
58
|
+
|
|
59
|
+
deploy:
|
|
60
|
+
environment:
|
|
61
|
+
name: github-pages
|
|
62
|
+
url: ${{ steps.deployment.outputs.page_url }}
|
|
63
|
+
runs-on: ubuntu-latest
|
|
64
|
+
needs: build
|
|
65
|
+
steps:
|
|
66
|
+
- name: Deploy to GitHub Pages
|
|
67
|
+
id: deployment
|
|
68
|
+
uses: actions/deploy-pages@v4
|
|
@@ -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.7.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,31 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
|
+
from collections.abc import Callable
|
|
4
|
+
import functools
|
|
3
5
|
import ipaddress
|
|
4
6
|
from typing import Annotated, Any
|
|
5
7
|
|
|
8
|
+
from mknodes.utils import classhelpers
|
|
6
9
|
from pathspec import gitignore
|
|
7
|
-
from pydantic import
|
|
10
|
+
from pydantic import (
|
|
11
|
+
BaseModel,
|
|
12
|
+
DirectoryPath,
|
|
13
|
+
Field,
|
|
14
|
+
HttpUrl,
|
|
15
|
+
ValidationInfo,
|
|
16
|
+
field_validator,
|
|
17
|
+
)
|
|
8
18
|
from pydantic.functional_validators import BeforeValidator
|
|
9
19
|
from pydantic_core import PydanticCustomError
|
|
10
20
|
|
|
21
|
+
from mkdocs_mknodes.appconfig import jinjaconfig, themeconfig, validationconfig
|
|
22
|
+
from mkdocs_mknodes.appconfig.base import ConfigFile
|
|
11
23
|
|
|
12
|
-
|
|
24
|
+
|
|
25
|
+
def validate_gitignore_patterns(pattern: list[str] | str) -> str:
|
|
13
26
|
"""Validate a list of gitignore patterns using pathspec."""
|
|
27
|
+
patterns = pattern.splitlines() if isinstance(pattern, str) else pattern
|
|
28
|
+
pattern_str = pattern if isinstance(pattern, str) else "\n".join(pattern)
|
|
14
29
|
try:
|
|
15
30
|
gitignore.GitIgnoreSpec.from_lines(patterns)
|
|
16
31
|
except Exception as e:
|
|
@@ -21,11 +36,11 @@ def validate_gitignore_patterns(patterns: list[str]) -> list[str]:
|
|
|
21
36
|
{"error": str(e)},
|
|
22
37
|
) from e
|
|
23
38
|
else:
|
|
24
|
-
return
|
|
39
|
+
return pattern_str
|
|
25
40
|
|
|
26
41
|
|
|
27
42
|
GitIgnorePatterns = Annotated[
|
|
28
|
-
|
|
43
|
+
str,
|
|
29
44
|
BeforeValidator(validate_gitignore_patterns),
|
|
30
45
|
]
|
|
31
46
|
|
|
@@ -39,109 +54,6 @@ class NavItem(BaseModel):
|
|
|
39
54
|
item: str | dict[str, NavItem]
|
|
40
55
|
|
|
41
56
|
|
|
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
57
|
class PluginConfig(BaseModel):
|
|
146
58
|
"""Configuration for a MkDocs plugin."""
|
|
147
59
|
|
|
@@ -151,7 +63,14 @@ class PluginConfig(BaseModel):
|
|
|
151
63
|
)
|
|
152
64
|
|
|
153
65
|
|
|
154
|
-
class
|
|
66
|
+
class ExtraJavascript(BaseModel):
|
|
67
|
+
path: str
|
|
68
|
+
type: str | None = None
|
|
69
|
+
async_: bool | None = Field(None, alias="async")
|
|
70
|
+
defer: bool | None = None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class AppConfig(ConfigFile):
|
|
155
74
|
"""The main configuration class for MkDocs projects.
|
|
156
75
|
|
|
157
76
|
This class defines all available settings for customizing your documentation site.
|
|
@@ -180,7 +99,7 @@ class AppConfig(BaseModel):
|
|
|
180
99
|
```
|
|
181
100
|
"""
|
|
182
101
|
|
|
183
|
-
site_url:
|
|
102
|
+
site_url: str | None = Field(None)
|
|
184
103
|
"""The canonical URL for your documentation site.
|
|
185
104
|
|
|
186
105
|
!!! info "Purpose"
|
|
@@ -323,6 +242,83 @@ class AppConfig(BaseModel):
|
|
|
323
242
|
- Staging environments
|
|
324
243
|
"""
|
|
325
244
|
|
|
245
|
+
build_fn: str = "mkdocs_mknodes:parse"
|
|
246
|
+
"""Path to the build script / callable.
|
|
247
|
+
|
|
248
|
+
Possible formats:
|
|
249
|
+
|
|
250
|
+
- `my.module:Class.build_fn` (must be a classmethod / staticmethod)
|
|
251
|
+
- `my.module:build_fn`
|
|
252
|
+
- `path/to/file.py:build_fn`
|
|
253
|
+
|
|
254
|
+
Can also be remote.
|
|
255
|
+
The targeted callable gets the project instance as an argument and optionally
|
|
256
|
+
keyword arguments from setting below.
|
|
257
|
+
"""
|
|
258
|
+
build_fn_arguments: dict[str, Any] | None = None
|
|
259
|
+
"""Keyword arguments passed to the build script / callable.
|
|
260
|
+
|
|
261
|
+
Build scripts may have keyword arguments. You can set them by using this setting.
|
|
262
|
+
"""
|
|
263
|
+
repo_path: str = "."
|
|
264
|
+
"""Path to the repository to create a website for. (`http://....my_project.git`)"""
|
|
265
|
+
clone_depth: int = 100
|
|
266
|
+
"""Clone depth in case the repository is remote. (Required for `git-changelog`)."""
|
|
267
|
+
build_folder: str | None = None
|
|
268
|
+
"""Folder to create the Markdown files in.
|
|
269
|
+
|
|
270
|
+
If no folder is set, **MkNodes** will generate a temporary dir."""
|
|
271
|
+
show_page_info: bool = True
|
|
272
|
+
"""Append an admonition box with build-related information.
|
|
273
|
+
|
|
274
|
+
If True, all pages get added an expandable admonition box at the bottom,
|
|
275
|
+
containing information about the created page.
|
|
276
|
+
This includes:
|
|
277
|
+
- Metadata
|
|
278
|
+
- Resources
|
|
279
|
+
- Code which created the page (needs the page to be created via decorators, or
|
|
280
|
+
the `generated_by` attribute of the `MkPage` needs to be set manually)
|
|
281
|
+
"""
|
|
282
|
+
rewrite_theme_templates: bool = True
|
|
283
|
+
"""Add additional functionality to themes by rewriting template files.
|
|
284
|
+
|
|
285
|
+
MkNodes can rewrite the HTML templates of Themes in order to add additional
|
|
286
|
+
functionality.
|
|
287
|
+
|
|
288
|
+
Right now, enabling this feature allows these options for the **Material-MkDocs**
|
|
289
|
+
theme:
|
|
290
|
+
- use iconify icons instead of the **Material-MkDocs** icons
|
|
291
|
+
- setting the theme features "navigation.indexes" and "navigation.expand" via
|
|
292
|
+
page metadata.
|
|
293
|
+
"""
|
|
294
|
+
auto_delete_generated_templates: bool = True
|
|
295
|
+
"""Delete the generated HTML templates when build is finished.
|
|
296
|
+
|
|
297
|
+
MkNodes may generate HTML template overrides during the build process and
|
|
298
|
+
deletes them after build. Using this setting, the deletion can be prevented.
|
|
299
|
+
"""
|
|
300
|
+
render_by_default: bool = True
|
|
301
|
+
"""Render all pages in the jinja environment.
|
|
302
|
+
|
|
303
|
+
This allows to render jinja in the **MkNodes** environment outside of the `MkJinja`
|
|
304
|
+
nodes.
|
|
305
|
+
|
|
306
|
+
This setting can be overridden by setting the page metadata field "render_macros".
|
|
307
|
+
"""
|
|
308
|
+
global_resources: bool = True
|
|
309
|
+
"""Make resources globally available.
|
|
310
|
+
|
|
311
|
+
If True, then the resources inferred from the nodes will be put into all HTML pages.
|
|
312
|
+
(This reflects the "default" MkDocs mechanism of putting extra CSS / JS into the
|
|
313
|
+
config file)
|
|
314
|
+
If False, then MkNodes will put the CSS / JS only into the pages which need it.
|
|
315
|
+
(the resources will be moved into the appropriate page template blocks)
|
|
316
|
+
"""
|
|
317
|
+
jinja_config: jinjaconfig.JinjaConfig = Field(default_factory=jinjaconfig.JinjaConfig)
|
|
318
|
+
"""Contains the configuration for the Jinja2 Environment.
|
|
319
|
+
|
|
320
|
+
Allows setting up loaders, extensions and the render behavior.
|
|
321
|
+
"""
|
|
326
322
|
docs_dir: DirectoryPath = Field("docs")
|
|
327
323
|
"""Directory containing documentation markdown source files.
|
|
328
324
|
|
|
@@ -386,7 +382,7 @@ class AppConfig(BaseModel):
|
|
|
386
382
|
```
|
|
387
383
|
"""
|
|
388
384
|
|
|
389
|
-
theme: ThemeConfig = Field(
|
|
385
|
+
theme: themeconfig.ThemeConfig = Field(default_factory=themeconfig.ThemeConfig)
|
|
390
386
|
"""The MkDocs theme for the documentation.
|
|
391
387
|
|
|
392
388
|
Can be a string for built-in themes or a theme config dict.
|
|
@@ -465,8 +461,8 @@ class AppConfig(BaseModel):
|
|
|
465
461
|
dev_addr: localhost:8080 # alternate port
|
|
466
462
|
```
|
|
467
463
|
"""
|
|
468
|
-
|
|
469
|
-
extra_css: list[
|
|
464
|
+
# pydantic.FilePath would be nice.. Looses bw compat to old mkdocs filess
|
|
465
|
+
extra_css: list[str] | None = Field(None)
|
|
470
466
|
"""Custom CSS files to include in the documentation.
|
|
471
467
|
|
|
472
468
|
!!! info "Processing"
|
|
@@ -488,7 +484,7 @@ class AppConfig(BaseModel):
|
|
|
488
484
|
```
|
|
489
485
|
"""
|
|
490
486
|
|
|
491
|
-
extra_javascript: list[
|
|
487
|
+
extra_javascript: list[str | ExtraJavascript] | None = Field(None)
|
|
492
488
|
"""Custom JavaScript files to include in the documentation.
|
|
493
489
|
|
|
494
490
|
!!! info "File Types"
|
|
@@ -511,7 +507,7 @@ class AppConfig(BaseModel):
|
|
|
511
507
|
Scripts are loaded after theme JavaScript files
|
|
512
508
|
"""
|
|
513
509
|
|
|
514
|
-
markdown_extensions: list[
|
|
510
|
+
markdown_extensions: list[dict[str, Any]] | None = Field(None)
|
|
515
511
|
"""PyMarkdown extensions and their configurations.
|
|
516
512
|
|
|
517
513
|
!!! info "Default Extensions"
|
|
@@ -571,7 +567,7 @@ class AppConfig(BaseModel):
|
|
|
571
567
|
```
|
|
572
568
|
"""
|
|
573
569
|
|
|
574
|
-
nav: list[
|
|
570
|
+
nav: list[dict[str, Any] | str] | None = Field(None)
|
|
575
571
|
"""Defines the hierarchical structure of the documentation navigation.
|
|
576
572
|
Each item can be a simple path to a file or a section with nested items.
|
|
577
573
|
|
|
@@ -604,27 +600,7 @@ class AppConfig(BaseModel):
|
|
|
604
600
|
```
|
|
605
601
|
"""
|
|
606
602
|
|
|
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)
|
|
603
|
+
extra: dict[str, Any] = Field(default_factory=dict)
|
|
628
604
|
"""A mapping/dictionary of custom data that is passed to the template.
|
|
629
605
|
|
|
630
606
|
This allows template authors to require extra configuration that is not
|
|
@@ -641,7 +617,7 @@ class AppConfig(BaseModel):
|
|
|
641
617
|
```
|
|
642
618
|
"""
|
|
643
619
|
|
|
644
|
-
validation:
|
|
620
|
+
validation: validationconfig.ValidationConfig | None = Field(None)
|
|
645
621
|
"""Controls the validation behavior for links, content, and navigation.
|
|
646
622
|
|
|
647
623
|
!!! info "Validation Levels"
|
|
@@ -672,8 +648,8 @@ class AppConfig(BaseModel):
|
|
|
672
648
|
omitted_files: strict
|
|
673
649
|
```
|
|
674
650
|
"""
|
|
675
|
-
|
|
676
|
-
watch: list[
|
|
651
|
+
# DirectoryPath would be nice
|
|
652
|
+
watch: list[str] | None = Field(None)
|
|
677
653
|
"""Additional directories to monitor for changes during development.
|
|
678
654
|
|
|
679
655
|
!!! info "Behavior"
|
|
@@ -690,7 +666,7 @@ class AppConfig(BaseModel):
|
|
|
690
666
|
```
|
|
691
667
|
"""
|
|
692
668
|
|
|
693
|
-
exclude_docs: GitIgnorePatterns = Field(
|
|
669
|
+
exclude_docs: GitIgnorePatterns = Field(default="")
|
|
694
670
|
"""Gitignore-style patterns for files to exclude from documentation.
|
|
695
671
|
|
|
696
672
|
!!! info "Pattern Syntax"
|
|
@@ -713,7 +689,7 @@ class AppConfig(BaseModel):
|
|
|
713
689
|
Patterns are relative to `docs_dir`
|
|
714
690
|
"""
|
|
715
691
|
|
|
716
|
-
not_in_nav: GitIgnorePatterns = Field(
|
|
692
|
+
not_in_nav: GitIgnorePatterns = Field(default="")
|
|
717
693
|
"""Patterns for files that should not generate warnings when not in navigation.
|
|
718
694
|
|
|
719
695
|
!!! info "Use Cases"
|
|
@@ -737,26 +713,55 @@ class AppConfig(BaseModel):
|
|
|
737
713
|
- Referenced programmatically
|
|
738
714
|
"""
|
|
739
715
|
|
|
740
|
-
@field_validator("plugins", mode="before")
|
|
716
|
+
@field_validator("plugins", "markdown_extensions", mode="before")
|
|
741
717
|
@classmethod
|
|
742
718
|
def convert_to_plugin_dict_list(
|
|
743
719
|
cls,
|
|
744
720
|
value: list[str | dict[str, dict[str, Any]]] | dict[str, Any],
|
|
721
|
+
info: ValidationInfo,
|
|
745
722
|
) -> list[dict[str, dict[str, Any]]]:
|
|
746
723
|
result: list[dict[str, Any]] = []
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
724
|
+
match value:
|
|
725
|
+
case dict():
|
|
726
|
+
# Convert dict to list of single-key dicts
|
|
727
|
+
for k, v in value.items():
|
|
728
|
+
result.append({k: v})
|
|
729
|
+
case list():
|
|
730
|
+
for item in value:
|
|
731
|
+
match item:
|
|
732
|
+
case str():
|
|
733
|
+
result.append({item: {}})
|
|
734
|
+
case dict():
|
|
735
|
+
if len(item) > 1:
|
|
736
|
+
f = info.field_name
|
|
737
|
+
msg = f"{f} dictionaries must have a single key"
|
|
738
|
+
raise ValueError(msg)
|
|
739
|
+
result.append(item)
|
|
740
|
+
case _:
|
|
741
|
+
type_str = f"{item!r} ({type(item)})"
|
|
742
|
+
f = info.field_name
|
|
743
|
+
msg = f"Invalid type for {f} section: {type_str}"
|
|
744
|
+
raise ValueError(msg)
|
|
758
745
|
return result
|
|
759
746
|
|
|
747
|
+
@field_validator("extra_javascript", mode="before")
|
|
748
|
+
@classmethod
|
|
749
|
+
def validate_extra_javascript(
|
|
750
|
+
cls, values: list[dict[str, Any] | str]
|
|
751
|
+
) -> list[ExtraJavascript | str]:
|
|
752
|
+
items: list[ExtraJavascript | str] = []
|
|
753
|
+
for value in values:
|
|
754
|
+
if isinstance(value, str):
|
|
755
|
+
if value.endswith(".mjs"):
|
|
756
|
+
item = ExtraJavascript(path=value, type="module")
|
|
757
|
+
items.append(item)
|
|
758
|
+
continue
|
|
759
|
+
items.append(value)
|
|
760
|
+
continue
|
|
761
|
+
item = ExtraJavascript(**value)
|
|
762
|
+
items.append(item)
|
|
763
|
+
return items
|
|
764
|
+
|
|
760
765
|
@field_validator("dev_addr", mode="before")
|
|
761
766
|
@classmethod
|
|
762
767
|
def validate_ip_port(cls, v: str) -> str:
|
|
@@ -771,15 +776,51 @@ class AppConfig(BaseModel):
|
|
|
771
776
|
raise ValueError(msg)
|
|
772
777
|
return v
|
|
773
778
|
|
|
779
|
+
def get_builder(self) -> Callable[..., Any]:
|
|
780
|
+
build_fn = classhelpers.to_callable(self.build_fn)
|
|
781
|
+
build_kwargs = self.build_fn_arguments or {}
|
|
782
|
+
return functools.partial(build_fn, **build_kwargs)
|
|
783
|
+
|
|
784
|
+
def set_theme(
|
|
785
|
+
self,
|
|
786
|
+
theme: str | dict[str, Any] | themeconfig.ThemeConfig,
|
|
787
|
+
**kwargs: Any,
|
|
788
|
+
):
|
|
789
|
+
match theme:
|
|
790
|
+
case themeconfig.ThemeConfig():
|
|
791
|
+
self.theme = theme
|
|
792
|
+
case dict():
|
|
793
|
+
self.theme = themeconfig.ThemeConfig(**{**theme, **kwargs})
|
|
794
|
+
case str():
|
|
795
|
+
self.theme = themeconfig.ThemeConfig(name=theme, **kwargs)
|
|
796
|
+
|
|
797
|
+
def remove_plugin(self, name: str):
|
|
798
|
+
for plg in self.plugins:
|
|
799
|
+
if plg == name or (isinstance(plg, dict) and next(iter(plg.keys())) == name):
|
|
800
|
+
self.plugins.remove(plg)
|
|
801
|
+
|
|
802
|
+
# @field_validator("theme", mode="before")
|
|
803
|
+
# @classmethod
|
|
804
|
+
# def validate_theme(cls, value: Any) -> ThemeConfig:
|
|
805
|
+
# if isinstance(value, dict):
|
|
806
|
+
# return themeconfig.ThemeConfig(**value)
|
|
807
|
+
# if isinstance(value, themeconfig.ThemeConfig):
|
|
808
|
+
# return value
|
|
809
|
+
# raise ValueError("Address must be either a dict or Address instance")
|
|
774
810
|
|
|
775
|
-
if __name__ == "__main__":
|
|
776
|
-
import pathlib
|
|
777
811
|
|
|
812
|
+
if __name__ == "__main__":
|
|
778
813
|
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
814
|
|
|
785
|
-
|
|
815
|
+
tests = [
|
|
816
|
+
"https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/mkdocs.yml",
|
|
817
|
+
# "https://raw.githubusercontent.com/fastapi-users/fastapi-users/master/mkdocs.yml",
|
|
818
|
+
# "https://raw.githubusercontent.com/pydantic/pydantic/main/mkdocs.yml",
|
|
819
|
+
# "https://raw.githubusercontent.com/facelessuser/pymdown-extensions/refs/heads/main/mkdocs.yml",
|
|
820
|
+
]
|
|
821
|
+
for url in tests:
|
|
822
|
+
config = AppConfig.from_yaml_file(url)
|
|
823
|
+
config.theme = dict(name="xyz", override_dir="overrides")
|
|
824
|
+
|
|
825
|
+
devtools.debug(config.theme)
|
|
826
|
+
print(config.theme, type(config.theme))
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from typing import Any, Self
|
|
5
|
+
|
|
6
|
+
from pydantic import BaseModel, Field
|
|
7
|
+
import yamling
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class ConfigFile(BaseModel):
|
|
11
|
+
"""Base class for config files.
|
|
12
|
+
|
|
13
|
+
A class for loading and managing configuration files in YAML format.
|
|
14
|
+
Supports inheritance between config files and provides methods for
|
|
15
|
+
loading from files or YAML text.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
config_file_path: str | None = Field(None, exclude=True)
|
|
19
|
+
# Either exclude here or add inherit field to MkNodesConfig?
|
|
20
|
+
inherit: str | None = Field(None, exclude=True, alias="INHERIT")
|
|
21
|
+
"""Define the parent for a configuration file.
|
|
22
|
+
|
|
23
|
+
The path must be relative to the location of the primary file.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
@classmethod
|
|
27
|
+
def from_yaml_file(cls, yaml_path: str | os.PathLike[str], **overrides: Any) -> Self:
|
|
28
|
+
"""Create a ConfigFile instance from a YAML file.
|
|
29
|
+
|
|
30
|
+
Args:
|
|
31
|
+
yaml_path: Path to the YAML configuration file
|
|
32
|
+
**overrides: Additional key-value pairs to override values from the file
|
|
33
|
+
|
|
34
|
+
Returns:
|
|
35
|
+
A new instance of the ConfigFile class initialized with the YAML data
|
|
36
|
+
"""
|
|
37
|
+
cfg = yamling.load_yaml_file(yaml_path)
|
|
38
|
+
vals = {"config_file_path": str(yaml_path), **cfg, **overrides}
|
|
39
|
+
return cls(**vals)
|
|
40
|
+
|
|
41
|
+
@classmethod
|
|
42
|
+
def from_yaml(cls, text: yamling.YAMLInput, **overrides: Any) -> Self:
|
|
43
|
+
"""Create a ConfigFile instance from YAML text.
|
|
44
|
+
|
|
45
|
+
Args:
|
|
46
|
+
text: YAML content as text or file-like object
|
|
47
|
+
**overrides: Additional key-value pairs to override values from the YAML
|
|
48
|
+
|
|
49
|
+
Returns:
|
|
50
|
+
A new instance of the ConfigFile class initialized with the YAML data
|
|
51
|
+
"""
|
|
52
|
+
cfg = yamling.load_yaml(text, resolve_inherit=True)
|
|
53
|
+
path = {"config_file_path": str(text.name)} if getattr(text, "name", None) else {} # type: ignore
|
|
54
|
+
vals = {**path, **cfg, **overrides}
|
|
55
|
+
return cls(**vals)
|
|
56
|
+
|
|
57
|
+
def to_yaml(self) -> str:
|
|
58
|
+
"""Convert the configuration to YAML format.
|
|
59
|
+
|
|
60
|
+
Returns:
|
|
61
|
+
A string containing the YAML representation of the configuration
|
|
62
|
+
"""
|
|
63
|
+
cfg = self.model_dump()
|
|
64
|
+
return yamling.dump_yaml(cfg)
|