mkdocs-mknodes 0.4.7__tar.gz → 0.4.9__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.4.7 → mkdocs_mknodes-0.4.9}/.github/workflows/build.yml +1 -1
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/workflows/documentation.yml +1 -1
- mkdocs_mknodes-0.4.9/.gitignore +48 -0
- mkdocs_mknodes-0.4.9/.pre-commit-config.yaml +49 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/PKG-INFO +7 -3
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/__init__.py +4 -1
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/buildcollector.py +5 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/cli/__init__.py +2 -4
- mkdocs_mknodes-0.4.9/mkdocs_mknodes/commands/build_page.py +222 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/__init__.py +3 -3
- mkdocs_mknodes-0.4.9/mkdocs_mknodes/telemetry.py +94 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/pyproject.toml +10 -4
- mkdocs_mknodes-0.4.7/.gitignore +0 -115
- mkdocs_mknodes-0.4.7/.pre-commit-config.yaml +0 -49
- mkdocs_mknodes-0.4.7/mkdocs_mknodes/commands/build_page.py +0 -154
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.editorconfig +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/README.md +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/dependabot.yml +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/LICENSE +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/README.md +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/configs/mkdocs_mkdocs.yml +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/configs/mkdocs_shared.yml +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/assets/cli.gif +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/build_process.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/cli_index.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/github_index.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/index.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/plugin_configuration.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/use_case_by_config.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/use_case_default_website.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/use_cases_index.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/why_should_i_use_mknodes.jinja +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/duties.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs.yml +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/__init__.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/buildbackend.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/buildcontext.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/cli/richstate.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/commands/__init__.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/commands/serve.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/commands/utils.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/__init__.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/cli_section.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/get_started_section.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/github_index.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/root.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/use_cases_section.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/mkdocsconfig.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/mknodesconfig.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/paths.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/mkdocsbuilder.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/pluginconfig.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/py.typed +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes.sublime-project +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/overrides/_dummy.txt +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/overrides/partials/actions.html +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/__init__.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/conftest.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/data/objects.inv +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/test_build.py +0 -0
- {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/test_cli.py +0 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
# Distribution / packaging
|
|
8
|
+
env/
|
|
9
|
+
dist/
|
|
10
|
+
.markdown/
|
|
11
|
+
*.sublime-workspace
|
|
12
|
+
|
|
13
|
+
# Unit test / coverage reports
|
|
14
|
+
htmlcov/
|
|
15
|
+
.coverage
|
|
16
|
+
.coverage.*
|
|
17
|
+
.cache
|
|
18
|
+
coverage.xml
|
|
19
|
+
.hypothesis/
|
|
20
|
+
.pytest_cache/
|
|
21
|
+
junit/
|
|
22
|
+
junit.xml
|
|
23
|
+
|
|
24
|
+
# pyenv
|
|
25
|
+
.python-version
|
|
26
|
+
|
|
27
|
+
# dotenv
|
|
28
|
+
.env
|
|
29
|
+
|
|
30
|
+
# virtualenv
|
|
31
|
+
.venv
|
|
32
|
+
venv/
|
|
33
|
+
ENV/
|
|
34
|
+
|
|
35
|
+
# mkdocs documentation
|
|
36
|
+
/site
|
|
37
|
+
|
|
38
|
+
# mypy
|
|
39
|
+
.mypy_cache/
|
|
40
|
+
|
|
41
|
+
# .vscode
|
|
42
|
+
.vscode/
|
|
43
|
+
|
|
44
|
+
# PyCharm
|
|
45
|
+
.idea/
|
|
46
|
+
|
|
47
|
+
# OS files
|
|
48
|
+
.DS_Store
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
default_language_version:
|
|
2
|
+
python: python3.12
|
|
3
|
+
default_stages: [pre-commit]
|
|
4
|
+
repos:
|
|
5
|
+
- repo: local
|
|
6
|
+
hooks:
|
|
7
|
+
- id: pytest-check
|
|
8
|
+
name: pytest-check
|
|
9
|
+
entry: uv run pytest
|
|
10
|
+
language: system
|
|
11
|
+
# stages: [push]
|
|
12
|
+
types: [python]
|
|
13
|
+
pass_filenames: false
|
|
14
|
+
always_run: true
|
|
15
|
+
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
16
|
+
rev: v5.0.0
|
|
17
|
+
hooks:
|
|
18
|
+
# - id: trailing-whitespace
|
|
19
|
+
# - id: check-ast
|
|
20
|
+
- id: check-case-conflict
|
|
21
|
+
- id: check-docstring-first
|
|
22
|
+
- id: check-merge-conflict
|
|
23
|
+
# - id: check-yaml
|
|
24
|
+
- id: check-toml
|
|
25
|
+
- id: check-json
|
|
26
|
+
- id: detect-private-key
|
|
27
|
+
- id: forbid-new-submodules
|
|
28
|
+
# - id: check-added-large-files
|
|
29
|
+
# https://pre-commit.com/hooks.html
|
|
30
|
+
|
|
31
|
+
- repo: https://github.com/pre-commit/mirrors-mypy
|
|
32
|
+
rev: v1.12.1
|
|
33
|
+
hooks:
|
|
34
|
+
- id: mypy
|
|
35
|
+
# args: [--ignore-missing-imports]
|
|
36
|
+
additional_dependencies: [mkdocs]
|
|
37
|
+
|
|
38
|
+
- repo: https://github.com/charliermarsh/ruff-pre-commit
|
|
39
|
+
rev: v0.7.0
|
|
40
|
+
hooks:
|
|
41
|
+
- id: ruff
|
|
42
|
+
- id: ruff-format
|
|
43
|
+
|
|
44
|
+
- repo: https://github.com/commitizen-tools/commitizen
|
|
45
|
+
rev: v3.29.1
|
|
46
|
+
hooks:
|
|
47
|
+
- id: commitizen
|
|
48
|
+
stages: [commit-msg]
|
|
49
|
+
additional_dependencies: [typing-extensions]
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: mkdocs-mknodes
|
|
3
|
-
Version: 0.4.
|
|
3
|
+
Version: 0.4.9
|
|
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
|
|
@@ -14,19 +14,23 @@ Classifier: Intended Audience :: Developers
|
|
|
14
14
|
Classifier: Operating System :: OS Independent
|
|
15
15
|
Classifier: Programming Language :: Python :: 3
|
|
16
16
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
18
17
|
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
19
|
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
20
20
|
Classifier: Topic :: Documentation
|
|
21
21
|
Classifier: Topic :: Internet
|
|
22
22
|
Classifier: Topic :: Software Development :: Documentation
|
|
23
23
|
Classifier: Topic :: Software Development :: User Interfaces
|
|
24
24
|
Classifier: Topic :: Text Processing :: Markup :: Markdown
|
|
25
|
-
Requires-Python: >=3.
|
|
25
|
+
Requires-Python: >=3.12
|
|
26
26
|
Requires-Dist: jinja2
|
|
27
27
|
Requires-Dist: jinjarope
|
|
28
|
+
Requires-Dist: logfire[aiohttp,httpx,requests,system-metrics]
|
|
28
29
|
Requires-Dist: mkdocs>=1.5
|
|
29
30
|
Requires-Dist: mknodes
|
|
31
|
+
Requires-Dist: opentelemetry-instrumentation-jinja2
|
|
32
|
+
Requires-Dist: opentelemetry-instrumentation-urllib
|
|
33
|
+
Requires-Dist: opentelemetry-instrumentation-urllib3
|
|
30
34
|
Requires-Dist: pathspec
|
|
31
35
|
Requires-Dist: rich
|
|
32
36
|
Requires-Dist: typer
|
|
@@ -8,6 +8,7 @@ import pathlib
|
|
|
8
8
|
import pprint
|
|
9
9
|
from typing import TYPE_CHECKING
|
|
10
10
|
|
|
11
|
+
import logfire
|
|
11
12
|
import mknodes as mk
|
|
12
13
|
from mknodes.utils import log, resources
|
|
13
14
|
|
|
@@ -227,6 +228,7 @@ class BuildCollector:
|
|
|
227
228
|
templates=templates,
|
|
228
229
|
)
|
|
229
230
|
|
|
231
|
+
@logfire.instrument("collect_page: {page.title}")
|
|
230
232
|
def collect_page(self, page: mk.MkPage):
|
|
231
233
|
"""Preprocess page and collect its data.
|
|
232
234
|
|
|
@@ -245,6 +247,7 @@ class BuildCollector:
|
|
|
245
247
|
if show_info:
|
|
246
248
|
add_page_info(page, req)
|
|
247
249
|
|
|
250
|
+
@logfire.instrument("render_page: {page.title}")
|
|
248
251
|
def render_page(self, page: mk.MkPage):
|
|
249
252
|
"""Convert a page to markdown/HTML.
|
|
250
253
|
|
|
@@ -260,6 +263,7 @@ class BuildCollector:
|
|
|
260
263
|
|
|
261
264
|
self.node_files[page.resolved_file_path] = md
|
|
262
265
|
|
|
266
|
+
@logfire.instrument("collect_nav: {nav.title}")
|
|
263
267
|
def collect_nav(self, nav: mk.MkNav):
|
|
264
268
|
"""Preprocess nav and collect its data.
|
|
265
269
|
|
|
@@ -273,6 +277,7 @@ class BuildCollector:
|
|
|
273
277
|
self.resources.merge(req)
|
|
274
278
|
update_nav_template(nav)
|
|
275
279
|
|
|
280
|
+
@logfire.instrument("render_nav: {nav.title}")
|
|
276
281
|
def render_nav(self, nav: mk.MkNav):
|
|
277
282
|
"""Convert a nav to markdown/HTML.
|
|
278
283
|
|
|
@@ -53,15 +53,13 @@ VERBOSE_CMDS = "-v", "--verbose"
|
|
|
53
53
|
QUIET_CMDS = "-q", "--quiet"
|
|
54
54
|
|
|
55
55
|
|
|
56
|
-
def verbose(ctx: t.Context,
|
|
57
|
-
# sourcery skip: move-assign
|
|
56
|
+
def verbose(ctx: t.Context, _param: t.CallbackParam, value: bool):
|
|
58
57
|
state = ctx.ensure_object(richstate.RichState)
|
|
59
58
|
if value:
|
|
60
59
|
state.stream.setLevel(logging.DEBUG)
|
|
61
60
|
|
|
62
61
|
|
|
63
|
-
def quiet(ctx: t.Context,
|
|
64
|
-
# sourcery skip: move-assign
|
|
62
|
+
def quiet(ctx: t.Context, _param: t.CallbackParam, value: bool):
|
|
65
63
|
state = ctx.ensure_object(richstate.RichState)
|
|
66
64
|
if value:
|
|
67
65
|
state.stream.setLevel(logging.ERROR)
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
"""The Mkdocs Plugin."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import io
|
|
6
|
+
import os
|
|
7
|
+
from typing import TYPE_CHECKING, Any
|
|
8
|
+
from urllib.parse import urljoin
|
|
9
|
+
|
|
10
|
+
import logfire
|
|
11
|
+
from mkdocs import exceptions
|
|
12
|
+
from mkdocs.commands import build as mkdocs_build
|
|
13
|
+
from mkdocs.config import load_config
|
|
14
|
+
from mkdocs.plugins import get_plugin_logger
|
|
15
|
+
from mkdocs.structure.files import InclusionLevel
|
|
16
|
+
from mkdocs.structure.nav import get_navigation
|
|
17
|
+
from mkdocs.structure.pages import Page
|
|
18
|
+
from mknodes.info import mkdocsconfigfile
|
|
19
|
+
from mknodes.utils import pathhelpers, yamlhelpers
|
|
20
|
+
|
|
21
|
+
from mkdocs_mknodes.commands import utils
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
if TYPE_CHECKING:
|
|
25
|
+
from mkdocs.config.defaults import MkDocsConfig
|
|
26
|
+
from mkdocs.structure.files import Files
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
logger = get_plugin_logger(__name__)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def build(
|
|
33
|
+
config_path: str | os.PathLike[str],
|
|
34
|
+
repo_path: str,
|
|
35
|
+
build_fn: str | None,
|
|
36
|
+
site_dir: str | None = None,
|
|
37
|
+
clone_depth: int = 100,
|
|
38
|
+
**kwargs: Any,
|
|
39
|
+
):
|
|
40
|
+
"""Build a MkNodes-based website.
|
|
41
|
+
|
|
42
|
+
Arguments:
|
|
43
|
+
config_path: The path to the config file to use
|
|
44
|
+
repo_path: Path to the repository a page should be built for
|
|
45
|
+
build_fn: Callable to use for creating the webpage
|
|
46
|
+
site_dir: Path for the website build
|
|
47
|
+
clone_depth: If repository is remote, the amount of commits to fetch
|
|
48
|
+
kwargs: Optional config values (overrides value from config)
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
def build_config():
|
|
52
|
+
cfg = mkdocsconfigfile.MkDocsConfigFile(config_path)
|
|
53
|
+
cfg.update_mknodes_section(
|
|
54
|
+
repo_url=repo_path,
|
|
55
|
+
build_fn=build_fn,
|
|
56
|
+
clone_depth=clone_depth,
|
|
57
|
+
)
|
|
58
|
+
if site_dir:
|
|
59
|
+
cfg["site_dir"] = site_dir
|
|
60
|
+
text = yamlhelpers.dump_yaml(dict(cfg))
|
|
61
|
+
buffer = io.StringIO(text)
|
|
62
|
+
buffer.name = config_path
|
|
63
|
+
config = load_config(buffer, **kwargs)
|
|
64
|
+
for k, v in config.items():
|
|
65
|
+
logger.debug("%s: %s", k, v)
|
|
66
|
+
return config
|
|
67
|
+
|
|
68
|
+
config = build_config()
|
|
69
|
+
with logfire.span("plugins callback: on_startup", config=config):
|
|
70
|
+
config.plugins.run_event("startup", command="build", dirty=False)
|
|
71
|
+
_build(config)
|
|
72
|
+
with logfire.span("plugins callback: shutdown", config=config):
|
|
73
|
+
config.plugins.run_event("shutdown")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
@utils.handle_exceptions
|
|
77
|
+
@utils.count_warnings
|
|
78
|
+
def _build(
|
|
79
|
+
config: MkDocsConfig,
|
|
80
|
+
live_server_url: str | None = None,
|
|
81
|
+
dirty: bool = False,
|
|
82
|
+
) -> None:
|
|
83
|
+
"""Build a MkNodes-based website. Also used for serving.
|
|
84
|
+
|
|
85
|
+
This method does NOT call the the startup / shutdown event hooks.
|
|
86
|
+
If that is desired, build() should be called.
|
|
87
|
+
|
|
88
|
+
Arguments:
|
|
89
|
+
config: Config to use
|
|
90
|
+
live_server_url: An optional URL of the live server to use
|
|
91
|
+
dirty: Do a dirty build
|
|
92
|
+
"""
|
|
93
|
+
inclusion = (
|
|
94
|
+
InclusionLevel.is_in_serve if live_server_url else InclusionLevel.is_included
|
|
95
|
+
)
|
|
96
|
+
with logfire.span("plugins callback: on_config", config=config):
|
|
97
|
+
config = config.plugins.on_config(config)
|
|
98
|
+
with logfire.span("plugins callback: on_pre_build", config=config):
|
|
99
|
+
config.plugins.on_pre_build(config=config)
|
|
100
|
+
|
|
101
|
+
if not dirty:
|
|
102
|
+
logger.info("Cleaning site directory")
|
|
103
|
+
pathhelpers.clean_directory(config.site_dir)
|
|
104
|
+
else: # pragma: no cover
|
|
105
|
+
logger.warning("A 'dirty' build is being performed (for site dev purposes only)")
|
|
106
|
+
if not live_server_url: # pragma: no cover
|
|
107
|
+
logger.info("Building documentation to directory: %s", config.site_dir)
|
|
108
|
+
if dirty and mkdocs_build.site_directory_contains_stale_files(config.site_dir):
|
|
109
|
+
logger.info("The directory contains stale files. Use --clean to remove them.")
|
|
110
|
+
# First gather all data from all files/pages to ensure all data is
|
|
111
|
+
# consistent across all pages.
|
|
112
|
+
files = utils.get_files(config)
|
|
113
|
+
env = config.theme.get_env()
|
|
114
|
+
files.add_files_from_theme(env, config)
|
|
115
|
+
with logfire.span("plugins callback: on_files", files=files, config=config):
|
|
116
|
+
files = config.plugins.on_files(files, config=config)
|
|
117
|
+
# If plugins have added files without setting inclusion level, calculate it again.
|
|
118
|
+
utils.set_exclusions(files._files, config)
|
|
119
|
+
nav = get_navigation(files, config)
|
|
120
|
+
# Run `nav` plugin events.
|
|
121
|
+
with logfire.span("plugins callback: on_nav", config=config, nav=nav):
|
|
122
|
+
nav = config.plugins.on_nav(nav, config=config, files=files)
|
|
123
|
+
logger.debug("Reading markdown pages.")
|
|
124
|
+
excluded: list[str] = []
|
|
125
|
+
with logfire.span("populate pages"):
|
|
126
|
+
for file in files.documentation_pages(inclusion=inclusion):
|
|
127
|
+
with logfire.span(f"populate page for {file.src_uri}", file=file):
|
|
128
|
+
logger.debug("Reading: %s", file.src_uri)
|
|
129
|
+
if file.page is None and file.inclusion.is_not_in_nav():
|
|
130
|
+
if live_server_url and file.inclusion.is_excluded():
|
|
131
|
+
excluded.append(urljoin(live_server_url, file.url))
|
|
132
|
+
Page(None, file, config)
|
|
133
|
+
assert file.page is not None
|
|
134
|
+
_populate_page(file.page, config, files, dirty)
|
|
135
|
+
if excluded:
|
|
136
|
+
excluded_str = "\n - ".join(excluded)
|
|
137
|
+
logger.info(
|
|
138
|
+
"The following pages are being built only for the preview "
|
|
139
|
+
"but will be excluded from `mkdocs build` per `draft_docs` config:"
|
|
140
|
+
"\n - %s",
|
|
141
|
+
excluded_str,
|
|
142
|
+
)
|
|
143
|
+
with logfire.span("plugins callback: on_env", env=env, config=config):
|
|
144
|
+
env = config.plugins.on_env(env, config=config, files=files)
|
|
145
|
+
logger.debug("Copying static assets.")
|
|
146
|
+
with logfire.span("copy_static_files"):
|
|
147
|
+
files.copy_static_files(dirty=dirty, inclusion=inclusion)
|
|
148
|
+
|
|
149
|
+
with logfire.span("build_templates"):
|
|
150
|
+
for template in config.theme.static_templates:
|
|
151
|
+
mkdocs_build._build_theme_template(template, env, files, config, nav)
|
|
152
|
+
for template in config.extra_templates:
|
|
153
|
+
mkdocs_build._build_extra_template(template, files, config, nav)
|
|
154
|
+
|
|
155
|
+
logger.debug("Building markdown pages.")
|
|
156
|
+
doc_files = files.documentation_pages(inclusion=inclusion)
|
|
157
|
+
with logfire.span("build_pages"):
|
|
158
|
+
for file in doc_files:
|
|
159
|
+
assert file.page
|
|
160
|
+
excl = file.inclusion.is_excluded()
|
|
161
|
+
with logfire.span(f"build_page {file.page.url}", page=file.page):
|
|
162
|
+
mkdocs_build._build_page(
|
|
163
|
+
file.page, config, doc_files, nav, env, dirty, excl
|
|
164
|
+
)
|
|
165
|
+
|
|
166
|
+
log_level = config.validation.links.anchors
|
|
167
|
+
with logfire.span("validate_anchor_links"):
|
|
168
|
+
for file in doc_files:
|
|
169
|
+
assert file.page is not None
|
|
170
|
+
file.page.validate_anchor_links(files=files, log_level=log_level)
|
|
171
|
+
# Run `post_build` plugin events.
|
|
172
|
+
with logfire.span("plugins callback: on_post_build", config=config):
|
|
173
|
+
config.plugins.on_post_build(config=config)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _populate_page(
|
|
177
|
+
page: Page, config: MkDocsConfig, files: Files, dirty: bool = False
|
|
178
|
+
) -> None:
|
|
179
|
+
"""Read page content from docs_dir and render Markdown."""
|
|
180
|
+
config._current_page = page
|
|
181
|
+
try:
|
|
182
|
+
# When --dirty is used, only read the page if the file has been modified since the
|
|
183
|
+
# previous build of the output.
|
|
184
|
+
if dirty and not page.file.is_modified():
|
|
185
|
+
return
|
|
186
|
+
|
|
187
|
+
with logfire.span("plugins callback: on_pre_page", page=page, config=config):
|
|
188
|
+
# Run the `pre_page` plugin event
|
|
189
|
+
page = config.plugins.on_pre_page(page, config=config, files=files)
|
|
190
|
+
|
|
191
|
+
with logfire.span("read_source", page=page):
|
|
192
|
+
page.read_source(config)
|
|
193
|
+
assert page.markdown is not None
|
|
194
|
+
|
|
195
|
+
# Run `page_markdown` plugin events.
|
|
196
|
+
with logfire.span("plugins callback: on_page_markdown", page=page, config=config):
|
|
197
|
+
page.markdown = config.plugins.on_page_markdown(
|
|
198
|
+
page.markdown, page=page, config=config, files=files
|
|
199
|
+
)
|
|
200
|
+
with logfire.span("render", page=page, config=config):
|
|
201
|
+
page.render(config, files)
|
|
202
|
+
assert page.content is not None
|
|
203
|
+
|
|
204
|
+
with logfire.span("plugins callback: on_page_content", page=page, config=config):
|
|
205
|
+
page.content = config.plugins.on_page_content(
|
|
206
|
+
page.content, page=page, config=config, files=files
|
|
207
|
+
)
|
|
208
|
+
except Exception as e:
|
|
209
|
+
message = f"Error reading page '{page.file.src_uri}':"
|
|
210
|
+
# Prevent duplicated error msg because it will be printed immediately afterwards.
|
|
211
|
+
if not isinstance(e, exceptions.BuildError):
|
|
212
|
+
message += f" {e}"
|
|
213
|
+
logger.exception(message)
|
|
214
|
+
raise
|
|
215
|
+
finally:
|
|
216
|
+
config._current_page = None
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
if __name__ == "__main__":
|
|
220
|
+
config = mkdocsconfigfile.MkDocsConfigFile("mkdocs.yml")
|
|
221
|
+
print(config.dump_config())
|
|
222
|
+
build("mkdocs.yml", ".", "mkdocs_mknodes.manual.root:Build.build")
|
|
@@ -7,14 +7,14 @@ import urllib.parse
|
|
|
7
7
|
import tempfile
|
|
8
8
|
from typing import TYPE_CHECKING, Literal
|
|
9
9
|
|
|
10
|
-
from mkdocs.plugins import BasePlugin
|
|
10
|
+
from mkdocs.plugins import BasePlugin
|
|
11
11
|
import mknodes as mk
|
|
12
12
|
from mknodes.info import contexts, folderinfo, linkprovider, reporegistry
|
|
13
13
|
from mknodes.utils import linkreplacer
|
|
14
14
|
|
|
15
15
|
import jinjarope
|
|
16
16
|
|
|
17
|
-
from mkdocs_mknodes import buildcollector, mkdocsconfig
|
|
17
|
+
from mkdocs_mknodes import buildcollector, mkdocsconfig, telemetry
|
|
18
18
|
from mkdocs_mknodes.backends import markdownbackend, mkdocsbackend
|
|
19
19
|
from mkdocs_mknodes.plugin import pluginconfig, rewriteloader
|
|
20
20
|
|
|
@@ -28,7 +28,7 @@ if TYPE_CHECKING:
|
|
|
28
28
|
# from mkdocs.utils.templates import TemplateContext
|
|
29
29
|
|
|
30
30
|
|
|
31
|
-
logger = get_plugin_logger(__name__)
|
|
31
|
+
logger = telemetry.get_plugin_logger(__name__)
|
|
32
32
|
|
|
33
33
|
CommandStr = Literal["build", "serve", "gh-deploy"]
|
|
34
34
|
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from collections.abc import MutableMapping
|
|
4
|
+
import logging
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
import logfire
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor
|
|
11
|
+
# from opentelemetry.instrumentation.urllib3 import URLLib3Instrumentor
|
|
12
|
+
# from opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor
|
|
13
|
+
# from opentelemetry.instrumentation.urllib import URLLibInstrumentor
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def setup_logfire():
|
|
17
|
+
code_source = logfire.CodeSource(
|
|
18
|
+
repository="https://github.com/phil65/mkdocs_mknodes",
|
|
19
|
+
revision="main",
|
|
20
|
+
root_path=".",
|
|
21
|
+
)
|
|
22
|
+
# console_opts = logfire.ConsoleOptions()
|
|
23
|
+
logfire.configure(
|
|
24
|
+
code_source=code_source,
|
|
25
|
+
console=False,
|
|
26
|
+
send_to_logfire="if-token-present",
|
|
27
|
+
)
|
|
28
|
+
# logger = logging.getLogger("mkdocs")
|
|
29
|
+
# handler = logfire.LogfireLoggingHandler()
|
|
30
|
+
# handler.setLevel(logging.DEBUG)
|
|
31
|
+
# logger.addHandler(handler)
|
|
32
|
+
# logging.basicConfig(level=logging.DEBUG)
|
|
33
|
+
# logger.setLevel(logging.DEBUG)
|
|
34
|
+
# Jinja2Instrumentor().instrument()
|
|
35
|
+
# SQLite3Instrumentor().instrument()
|
|
36
|
+
# URLLib3Instrumentor().instrument()
|
|
37
|
+
# URLLibInstrumentor().instrument()
|
|
38
|
+
logfire.instrument_requests()
|
|
39
|
+
logfire.instrument_system_metrics()
|
|
40
|
+
logfire.instrument_aiohttp_client()
|
|
41
|
+
# logfire.instrument_httpx()
|
|
42
|
+
# logfire.install_auto_tracing("mkdocs")
|
|
43
|
+
|
|
44
|
+
# litellm.success_callback = ["logfire"]
|
|
45
|
+
# litellm.callbacks = ["logfire"]
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class PrefixedLogger(logging.LoggerAdapter):
|
|
49
|
+
"""A logger adapter to prefix log messages."""
|
|
50
|
+
|
|
51
|
+
def __init__(self, prefix: str, logger: logging.Logger) -> None:
|
|
52
|
+
"""Initialize the logger adapter.
|
|
53
|
+
|
|
54
|
+
Arguments:
|
|
55
|
+
prefix: The string to insert in front of every message.
|
|
56
|
+
logger: The logger instance.
|
|
57
|
+
"""
|
|
58
|
+
super().__init__(logger, {})
|
|
59
|
+
self.prefix = prefix
|
|
60
|
+
|
|
61
|
+
def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, Any]:
|
|
62
|
+
"""Process the message.
|
|
63
|
+
|
|
64
|
+
Arguments:
|
|
65
|
+
msg: The message:
|
|
66
|
+
kwargs: Remaining arguments.
|
|
67
|
+
|
|
68
|
+
Returns:
|
|
69
|
+
The processed message.
|
|
70
|
+
"""
|
|
71
|
+
return f"{self.prefix}: {msg}", kwargs
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def get_plugin_logger(name: str) -> PrefixedLogger:
|
|
75
|
+
"""Return a logger for plugins.
|
|
76
|
+
|
|
77
|
+
Arguments:
|
|
78
|
+
name: The name to use with `logging.getLogger`.
|
|
79
|
+
|
|
80
|
+
Returns:
|
|
81
|
+
A logger configured to work well in MkDocs,
|
|
82
|
+
prefixing each message with the plugin package name.
|
|
83
|
+
|
|
84
|
+
Example:
|
|
85
|
+
```python
|
|
86
|
+
from mkdocs.plugins import get_plugin_logger
|
|
87
|
+
|
|
88
|
+
log = get_plugin_logger(__name__)
|
|
89
|
+
log.info("My plugin message")
|
|
90
|
+
```
|
|
91
|
+
"""
|
|
92
|
+
logger = logging.getLogger(f"mkdocs.plugins.{name}")
|
|
93
|
+
logger.addHandler(logfire.LogfireLoggingHandler())
|
|
94
|
+
return PrefixedLogger(name.split(".", 1)[0], logger)
|
|
@@ -12,8 +12,8 @@ classifiers = [
|
|
|
12
12
|
"Operating System :: OS Independent",
|
|
13
13
|
"Programming Language :: Python :: 3",
|
|
14
14
|
"Programming Language :: Python :: 3 :: Only",
|
|
15
|
-
"Programming Language :: Python :: 3.11",
|
|
16
15
|
"Programming Language :: Python :: 3.12",
|
|
16
|
+
"Programming Language :: Python :: 3.13",
|
|
17
17
|
"Programming Language :: Python :: Implementation :: CPython",
|
|
18
18
|
"Topic :: Software Development :: Documentation",
|
|
19
19
|
"Topic :: Software Development :: User Interfaces",
|
|
@@ -30,7 +30,7 @@ keywords = [
|
|
|
30
30
|
"markdown",
|
|
31
31
|
]
|
|
32
32
|
|
|
33
|
-
requires-python = ">=3.
|
|
33
|
+
requires-python = ">=3.12"
|
|
34
34
|
dependencies = [
|
|
35
35
|
# MkDocs
|
|
36
36
|
"mkdocs >=1.5",
|
|
@@ -43,6 +43,11 @@ dependencies = [
|
|
|
43
43
|
"jinja2",
|
|
44
44
|
"jinjarope",
|
|
45
45
|
"universal_pathlib",
|
|
46
|
+
"logfire[requests,httpx,aiohttp,system-metrics]",
|
|
47
|
+
"opentelemetry-instrumentation-urllib3",
|
|
48
|
+
# "opentelemetry-instrumentation-sqlite3",
|
|
49
|
+
"opentelemetry-instrumentation-urllib",
|
|
50
|
+
"opentelemetry-instrumentation-jinja2",
|
|
46
51
|
]
|
|
47
52
|
license = "MIT"
|
|
48
53
|
|
|
@@ -109,7 +114,7 @@ exclude_lines = [
|
|
|
109
114
|
]
|
|
110
115
|
|
|
111
116
|
[tool.mypy]
|
|
112
|
-
python_version = "3.
|
|
117
|
+
python_version = "3.12"
|
|
113
118
|
disable_error_code = ["assignment", "misc", "import", "has-type"]
|
|
114
119
|
pretty = true
|
|
115
120
|
|
|
@@ -118,7 +123,7 @@ line-length = 90
|
|
|
118
123
|
extend-exclude = [
|
|
119
124
|
'docs',
|
|
120
125
|
]
|
|
121
|
-
target-version = "
|
|
126
|
+
target-version = "py312"
|
|
122
127
|
|
|
123
128
|
[tool.ruff.lint]
|
|
124
129
|
select = [
|
|
@@ -237,6 +242,7 @@ combine-as-imports = true
|
|
|
237
242
|
reportUnusedCallResult = false
|
|
238
243
|
reportUnknownVariableType = false
|
|
239
244
|
reportImplicitOverride = false
|
|
245
|
+
reportAny = false
|
|
240
246
|
|
|
241
247
|
[tool.mknodes]
|
|
242
248
|
allowed-commit-types = [
|
mkdocs_mknodes-0.4.7/.gitignore
DELETED
|
@@ -1,115 +0,0 @@
|
|
|
1
|
-
# Byte-compiled / optimized / DLL files
|
|
2
|
-
__pycache__/
|
|
3
|
-
*.py[cod]
|
|
4
|
-
*$py.class
|
|
5
|
-
|
|
6
|
-
# C extensions
|
|
7
|
-
*.so
|
|
8
|
-
|
|
9
|
-
# Distribution / packaging
|
|
10
|
-
.Python
|
|
11
|
-
env/
|
|
12
|
-
build/
|
|
13
|
-
develop-eggs/
|
|
14
|
-
dist/
|
|
15
|
-
downloads/
|
|
16
|
-
eggs/
|
|
17
|
-
.eggs/
|
|
18
|
-
.markdown/
|
|
19
|
-
lib/
|
|
20
|
-
lib64/
|
|
21
|
-
parts/
|
|
22
|
-
sdist/
|
|
23
|
-
var/
|
|
24
|
-
wheels/
|
|
25
|
-
*.sublime-workspace
|
|
26
|
-
*.egg-info/
|
|
27
|
-
.installed.cfg
|
|
28
|
-
*.egg
|
|
29
|
-
|
|
30
|
-
# PyInstaller
|
|
31
|
-
# Usually these files are written by a python script from a template
|
|
32
|
-
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
33
|
-
*.manifest
|
|
34
|
-
*.spec
|
|
35
|
-
|
|
36
|
-
# Installer logs
|
|
37
|
-
pip-log.txt
|
|
38
|
-
pip-delete-this-directory.txt
|
|
39
|
-
|
|
40
|
-
# Unit test / coverage reports
|
|
41
|
-
htmlcov/
|
|
42
|
-
.tox/
|
|
43
|
-
.coverage
|
|
44
|
-
.coverage.*
|
|
45
|
-
.cache
|
|
46
|
-
.hatch
|
|
47
|
-
nosetests.xml
|
|
48
|
-
coverage.xml
|
|
49
|
-
*.cover
|
|
50
|
-
.hypothesis/
|
|
51
|
-
.pytest_cache/
|
|
52
|
-
junit/
|
|
53
|
-
junit.xml
|
|
54
|
-
test.db
|
|
55
|
-
|
|
56
|
-
# Translations
|
|
57
|
-
*.mo
|
|
58
|
-
*.pot
|
|
59
|
-
|
|
60
|
-
# Django stuff:
|
|
61
|
-
*.log
|
|
62
|
-
local_settings.py
|
|
63
|
-
pdm.lock
|
|
64
|
-
.pdm-python
|
|
65
|
-
# Flask stuff:
|
|
66
|
-
instance/
|
|
67
|
-
.webassets-cache
|
|
68
|
-
|
|
69
|
-
# Scrapy stuff:
|
|
70
|
-
.scrapy
|
|
71
|
-
|
|
72
|
-
# Sphinx documentation
|
|
73
|
-
docs/_build/
|
|
74
|
-
|
|
75
|
-
# PyBuilder
|
|
76
|
-
target/
|
|
77
|
-
|
|
78
|
-
# Jupyter Notebook
|
|
79
|
-
.ipynb_checkpoints
|
|
80
|
-
|
|
81
|
-
# pyenv
|
|
82
|
-
.python-version
|
|
83
|
-
|
|
84
|
-
# celery beat schedule file
|
|
85
|
-
celerybeat-schedule
|
|
86
|
-
|
|
87
|
-
# SageMath parsed files
|
|
88
|
-
*.sage.py
|
|
89
|
-
|
|
90
|
-
# dotenv
|
|
91
|
-
.env
|
|
92
|
-
|
|
93
|
-
# virtualenv
|
|
94
|
-
.venv
|
|
95
|
-
venv/
|
|
96
|
-
ENV/
|
|
97
|
-
|
|
98
|
-
# Spyder project settings
|
|
99
|
-
.spyderproject
|
|
100
|
-
.spyproject
|
|
101
|
-
|
|
102
|
-
# Rope project settings
|
|
103
|
-
.ropeproject
|
|
104
|
-
|
|
105
|
-
# mkdocs documentation
|
|
106
|
-
/site
|
|
107
|
-
|
|
108
|
-
# mypy
|
|
109
|
-
.mypy_cache/
|
|
110
|
-
|
|
111
|
-
# .vscode
|
|
112
|
-
.vscode/
|
|
113
|
-
|
|
114
|
-
# OS files
|
|
115
|
-
.DS_Store
|
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
default_language_version:
|
|
2
|
-
python: python3.11
|
|
3
|
-
default_stages: [pre-commit]
|
|
4
|
-
repos:
|
|
5
|
-
- repo: local
|
|
6
|
-
hooks:
|
|
7
|
-
- id: pytest-check
|
|
8
|
-
name: pytest-check
|
|
9
|
-
entry: uv run pytest
|
|
10
|
-
language: system
|
|
11
|
-
# stages: [push]
|
|
12
|
-
types: [python]
|
|
13
|
-
pass_filenames: false
|
|
14
|
-
always_run: true
|
|
15
|
-
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
16
|
-
rev: v5.0.0
|
|
17
|
-
hooks:
|
|
18
|
-
# - id: trailing-whitespace
|
|
19
|
-
# - id: check-ast
|
|
20
|
-
- id: check-case-conflict
|
|
21
|
-
- id: check-docstring-first
|
|
22
|
-
- id: check-merge-conflict
|
|
23
|
-
# - id: check-yaml
|
|
24
|
-
- id: check-toml
|
|
25
|
-
- id: check-json
|
|
26
|
-
- id: detect-private-key
|
|
27
|
-
- id: forbid-new-submodules
|
|
28
|
-
# - id: check-added-large-files
|
|
29
|
-
# https://pre-commit.com/hooks.html
|
|
30
|
-
|
|
31
|
-
- repo: https://github.com/pre-commit/mirrors-mypy
|
|
32
|
-
rev: v1.12.0
|
|
33
|
-
hooks:
|
|
34
|
-
- id: mypy
|
|
35
|
-
# args: [--ignore-missing-imports]
|
|
36
|
-
additional_dependencies: [mkdocs]
|
|
37
|
-
|
|
38
|
-
- repo: https://github.com/charliermarsh/ruff-pre-commit
|
|
39
|
-
rev: v0.6.9
|
|
40
|
-
hooks:
|
|
41
|
-
- id: ruff
|
|
42
|
-
- id: ruff-format
|
|
43
|
-
|
|
44
|
-
- repo: https://github.com/commitizen-tools/commitizen
|
|
45
|
-
rev: v3.29.1
|
|
46
|
-
hooks:
|
|
47
|
-
- id: commitizen
|
|
48
|
-
stages: [commit-msg]
|
|
49
|
-
additional_dependencies: [typing-extensions]
|
|
@@ -1,154 +0,0 @@
|
|
|
1
|
-
"""The Mkdocs Plugin."""
|
|
2
|
-
|
|
3
|
-
from __future__ import annotations
|
|
4
|
-
|
|
5
|
-
import io
|
|
6
|
-
import os
|
|
7
|
-
from typing import TYPE_CHECKING, Any
|
|
8
|
-
from urllib.parse import urljoin
|
|
9
|
-
|
|
10
|
-
from mkdocs.commands import build as mkdocs_build
|
|
11
|
-
from mkdocs.config import load_config
|
|
12
|
-
from mkdocs.plugins import get_plugin_logger
|
|
13
|
-
from mkdocs.structure.files import InclusionLevel
|
|
14
|
-
from mkdocs.structure.nav import get_navigation
|
|
15
|
-
from mkdocs.structure.pages import Page
|
|
16
|
-
from mknodes.info import mkdocsconfigfile
|
|
17
|
-
from mknodes.utils import pathhelpers, yamlhelpers
|
|
18
|
-
|
|
19
|
-
from mkdocs_mknodes.commands import utils
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
if TYPE_CHECKING:
|
|
23
|
-
from mkdocs.config.defaults import MkDocsConfig
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
logger = get_plugin_logger(__name__)
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
def build(
|
|
30
|
-
config_path: str | os.PathLike[str],
|
|
31
|
-
repo_path: str,
|
|
32
|
-
build_fn: str | None,
|
|
33
|
-
site_dir: str | None = None,
|
|
34
|
-
clone_depth: int = 100,
|
|
35
|
-
**kwargs: Any,
|
|
36
|
-
):
|
|
37
|
-
"""Build a MkNodes-based website.
|
|
38
|
-
|
|
39
|
-
Arguments:
|
|
40
|
-
config_path: The path to the config file to use
|
|
41
|
-
repo_path: Path to the repository a page should be built for
|
|
42
|
-
build_fn: Callable to use for creating the webpage
|
|
43
|
-
site_dir: Path for the website build
|
|
44
|
-
clone_depth: If repository is remote, the amount of commits to fetch
|
|
45
|
-
kwargs: Optional config values (overrides value from config)
|
|
46
|
-
"""
|
|
47
|
-
cfg = mkdocsconfigfile.MkDocsConfigFile(config_path)
|
|
48
|
-
cfg.update_mknodes_section(
|
|
49
|
-
repo_url=repo_path,
|
|
50
|
-
build_fn=build_fn,
|
|
51
|
-
clone_depth=clone_depth,
|
|
52
|
-
)
|
|
53
|
-
if site_dir:
|
|
54
|
-
cfg["site_dir"] = site_dir
|
|
55
|
-
text = yamlhelpers.dump_yaml(dict(cfg))
|
|
56
|
-
buffer = io.StringIO(text)
|
|
57
|
-
buffer.name = config_path
|
|
58
|
-
config = load_config(buffer, **kwargs)
|
|
59
|
-
for k, v in config.items():
|
|
60
|
-
logger.debug("%s: %s", k, v)
|
|
61
|
-
config.plugins.run_event("startup", command="build", dirty=False)
|
|
62
|
-
_build(config)
|
|
63
|
-
config.plugins.run_event("shutdown")
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
@utils.handle_exceptions
|
|
67
|
-
@utils.count_warnings
|
|
68
|
-
def _build(
|
|
69
|
-
config: MkDocsConfig,
|
|
70
|
-
live_server_url: str | None = None,
|
|
71
|
-
dirty: bool = False,
|
|
72
|
-
) -> None:
|
|
73
|
-
"""Build a MkNodes-based website. Also used for serving.
|
|
74
|
-
|
|
75
|
-
This method does NOT call the the startup / shutdown event hooks.
|
|
76
|
-
If that is desired, build() should be called.
|
|
77
|
-
|
|
78
|
-
Arguments:
|
|
79
|
-
config: Config to use
|
|
80
|
-
live_server_url: An optional URL of the live server to use
|
|
81
|
-
dirty: Do a dirty build
|
|
82
|
-
"""
|
|
83
|
-
inclusion = (
|
|
84
|
-
InclusionLevel.is_in_serve if live_server_url else InclusionLevel.is_included
|
|
85
|
-
)
|
|
86
|
-
config = config.plugins.on_config(config)
|
|
87
|
-
config.plugins.on_pre_build(config=config)
|
|
88
|
-
|
|
89
|
-
if not dirty:
|
|
90
|
-
logger.info("Cleaning site directory")
|
|
91
|
-
pathhelpers.clean_directory(config.site_dir)
|
|
92
|
-
else: # pragma: no cover
|
|
93
|
-
logger.warning("A 'dirty' build is being performed (for site dev purposes only)")
|
|
94
|
-
if not live_server_url: # pragma: no cover
|
|
95
|
-
logger.info("Building documentation to directory: %s", config.site_dir)
|
|
96
|
-
if dirty and mkdocs_build.site_directory_contains_stale_files(config.site_dir):
|
|
97
|
-
logger.info("The directory contains stale files. Use --clean to remove them.")
|
|
98
|
-
# First gather all data from all files/pages to ensure all data is
|
|
99
|
-
# consistent across all pages.
|
|
100
|
-
files = utils.get_files(config)
|
|
101
|
-
env = config.theme.get_env()
|
|
102
|
-
files.add_files_from_theme(env, config)
|
|
103
|
-
files = config.plugins.on_files(files, config=config)
|
|
104
|
-
# If plugins have added files without setting inclusion level, calculate it again.
|
|
105
|
-
utils.set_exclusions(files._files, config)
|
|
106
|
-
nav = get_navigation(files, config)
|
|
107
|
-
# Run `nav` plugin events.
|
|
108
|
-
nav = config.plugins.on_nav(nav, config=config, files=files)
|
|
109
|
-
logger.debug("Reading markdown pages.")
|
|
110
|
-
excluded: list[str] = []
|
|
111
|
-
for file in files.documentation_pages(inclusion=inclusion):
|
|
112
|
-
logger.debug("Reading: %s", file.src_uri)
|
|
113
|
-
if file.page is None and file.inclusion.is_not_in_nav():
|
|
114
|
-
if live_server_url and file.inclusion.is_excluded():
|
|
115
|
-
excluded.append(urljoin(live_server_url, file.url))
|
|
116
|
-
Page(None, file, config)
|
|
117
|
-
assert file.page is not None
|
|
118
|
-
mkdocs_build._populate_page(file.page, config, files, dirty)
|
|
119
|
-
if excluded:
|
|
120
|
-
excluded_str = "\n - ".join(excluded)
|
|
121
|
-
logger.info(
|
|
122
|
-
"The following pages are being built only for the preview "
|
|
123
|
-
"but will be excluded from `mkdocs build` per `draft_docs` config:"
|
|
124
|
-
"\n - %s",
|
|
125
|
-
excluded_str,
|
|
126
|
-
)
|
|
127
|
-
env = config.plugins.on_env(env, config=config, files=files)
|
|
128
|
-
logger.debug("Copying static assets.")
|
|
129
|
-
files.copy_static_files(dirty=dirty, inclusion=inclusion)
|
|
130
|
-
|
|
131
|
-
for template in config.theme.static_templates:
|
|
132
|
-
mkdocs_build._build_theme_template(template, env, files, config, nav)
|
|
133
|
-
for template in config.extra_templates:
|
|
134
|
-
mkdocs_build._build_extra_template(template, files, config, nav)
|
|
135
|
-
|
|
136
|
-
logger.debug("Building markdown pages.")
|
|
137
|
-
doc_files = files.documentation_pages(inclusion=inclusion)
|
|
138
|
-
for file in doc_files:
|
|
139
|
-
assert file.page
|
|
140
|
-
excl = file.inclusion.is_excluded()
|
|
141
|
-
mkdocs_build._build_page(file.page, config, doc_files, nav, env, dirty, excl)
|
|
142
|
-
|
|
143
|
-
log_level = config.validation.links.anchors
|
|
144
|
-
for file in doc_files:
|
|
145
|
-
assert file.page is not None
|
|
146
|
-
file.page.validate_anchor_links(files=files, log_level=log_level)
|
|
147
|
-
# Run `post_build` plugin events.
|
|
148
|
-
config.plugins.on_post_build(config=config)
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
if __name__ == "__main__":
|
|
152
|
-
config = mkdocsconfigfile.MkDocsConfigFile("mkdocs.yml")
|
|
153
|
-
print(config.dump_config())
|
|
154
|
-
build("mkdocs.yml", ".", "mkdocs_mknodes.manual.root:Build.build")
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|