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.
Files changed (68) hide show
  1. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/workflows/build.yml +1 -1
  2. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/workflows/documentation.yml +1 -1
  3. mkdocs_mknodes-0.4.9/.gitignore +48 -0
  4. mkdocs_mknodes-0.4.9/.pre-commit-config.yaml +49 -0
  5. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/PKG-INFO +7 -3
  6. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/__init__.py +4 -1
  7. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/buildcollector.py +5 -0
  8. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/cli/__init__.py +2 -4
  9. mkdocs_mknodes-0.4.9/mkdocs_mknodes/commands/build_page.py +222 -0
  10. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/__init__.py +3 -3
  11. mkdocs_mknodes-0.4.9/mkdocs_mknodes/telemetry.py +94 -0
  12. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/pyproject.toml +10 -4
  13. mkdocs_mknodes-0.4.7/.gitignore +0 -115
  14. mkdocs_mknodes-0.4.7/.pre-commit-config.yaml +0 -49
  15. mkdocs_mknodes-0.4.7/mkdocs_mknodes/commands/build_page.py +0 -154
  16. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.editorconfig +0 -0
  17. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/README.md +0 -0
  18. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/.github/dependabot.yml +0 -0
  19. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/LICENSE +0 -0
  20. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/README.md +0 -0
  21. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/configs/mkdocs_mkdocs.yml +0 -0
  22. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/configs/mkdocs_shared.yml +0 -0
  23. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/assets/cli.gif +0 -0
  24. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/build_process.jinja +0 -0
  25. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/cli_index.jinja +0 -0
  26. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/github_index.jinja +0 -0
  27. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/index.jinja +0 -0
  28. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/plugin_configuration.jinja +0 -0
  29. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/use_case_by_config.jinja +0 -0
  30. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/use_case_default_website.jinja +0 -0
  31. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/use_cases_index.jinja +0 -0
  32. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/docs/why_should_i_use_mknodes.jinja +0 -0
  33. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/duties.py +0 -0
  34. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs.yml +0 -0
  35. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/__init__.py +0 -0
  36. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/buildbackend.py +0 -0
  37. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
  38. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
  39. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/buildcontext.py +0 -0
  40. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/cli/richstate.py +0 -0
  41. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/commands/__init__.py +0 -0
  42. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/commands/serve.py +0 -0
  43. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/commands/utils.py +0 -0
  44. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/__init__.py +0 -0
  45. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/cli_section.py +0 -0
  46. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/get_started_section.py +0 -0
  47. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/github_index.py +0 -0
  48. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/root.py +0 -0
  49. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/manual/use_cases_section.py +0 -0
  50. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
  51. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/mkdocsconfig.py +0 -0
  52. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/mknodesconfig.py +0 -0
  53. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/paths.py +0 -0
  54. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/mkdocsbuilder.py +0 -0
  55. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
  56. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/pluginconfig.py +0 -0
  57. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
  58. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/py.typed +0 -0
  59. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -0
  60. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
  61. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/mkdocs_mknodes.sublime-project +0 -0
  62. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/overrides/_dummy.txt +0 -0
  63. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/overrides/partials/actions.html +0 -0
  64. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/__init__.py +0 -0
  65. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/conftest.py +0 -0
  66. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/data/objects.inv +0 -0
  67. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/test_build.py +0 -0
  68. {mkdocs_mknodes-0.4.7 → mkdocs_mknodes-0.4.9}/tests/test_cli.py +0 -0
@@ -7,7 +7,7 @@ jobs:
7
7
  runs-on: ubuntu-latest
8
8
  strategy:
9
9
  matrix:
10
- python_version: ["3.11", "3.12", "3.13"]
10
+ python_version: ["3.12", "3.13"]
11
11
 
12
12
  steps:
13
13
  - name: Check out repository
@@ -32,7 +32,7 @@ jobs:
32
32
  - name: Set up Python
33
33
  uses: actions/setup-python@v5
34
34
  with:
35
- python-version: "3.11"
35
+ python-version: "3.12"
36
36
  - name: Setup Graphviz
37
37
  uses: ts-graphviz/setup-graphviz@v2
38
38
  - name: Install uv
@@ -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.7
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.11
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
@@ -1,6 +1,9 @@
1
- __version__ = "0.4.7"
1
+ __version__ = "0.4.9"
2
2
 
3
3
 
4
4
  from .mkdefaultwebsite import MkDefaultWebsite
5
+ from . import telemetry
6
+
7
+ telemetry.setup_logfire()
5
8
 
6
9
  __all__ = ["MkDefaultWebsite"]
@@ -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, param: t.CallbackParam, value: bool):
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, param: t.CallbackParam, value: bool):
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, get_plugin_logger
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.11"
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.11"
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 = "py311"
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 = [
@@ -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