mkdocs-mknodes 0.6.2__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.
Files changed (77) hide show
  1. mkdocs_mknodes-0.7.2/.github/workflows/documentation.yml +68 -0
  2. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/PKG-INFO +1 -1
  3. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/__init__.py +1 -1
  4. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/appconfig.py +11 -19
  5. mkdocs_mknodes-0.7.2/mkdocs_mknodes/appconfig/base.py +64 -0
  6. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/builders/configbuilder.py +3 -4
  7. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/build_page.py +69 -16
  8. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/serve.py +12 -8
  9. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/utils.py +5 -5
  10. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/mkdocsconfig.py +5 -15
  11. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/__init__.py +13 -5
  12. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mkdocsbuilder.py +8 -3
  13. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mknodesconfig.py +14 -11
  14. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/pluginconfig.py +2 -1
  15. mkdocs_mknodes-0.6.2/.github/workflows/documentation.yml +0 -68
  16. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.editorconfig +0 -0
  17. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.github/README.md +0 -0
  18. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.github/copilot-instructions.md +0 -0
  19. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.github/dependabot.yml +0 -0
  20. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.github/workflows/build.yml +0 -0
  21. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.gitignore +0 -0
  22. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/.pre-commit-config.yaml +0 -0
  23. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/LICENSE +0 -0
  24. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/README.md +0 -0
  25. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/configs/mkdocs_mkdocs.yml +0 -0
  26. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/configs/mkdocs_shared.yml +0 -0
  27. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/assets/cli.gif +0 -0
  28. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/build_process.jinja +0 -0
  29. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/cli_index.jinja +0 -0
  30. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/github_index.jinja +0 -0
  31. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/index.jinja +0 -0
  32. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/plugin_configuration.jinja +0 -0
  33. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/use_case_by_config.jinja +0 -0
  34. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/use_case_default_website.jinja +0 -0
  35. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/use_cases_index.jinja +0 -0
  36. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/docs/why_should_i_use_mknodes.jinja +0 -0
  37. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/duties.py +0 -0
  38. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs.yml +0 -0
  39. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/__init__.py +0 -0
  40. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/jinjaconfig.py +0 -0
  41. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/themeconfig.py +0 -0
  42. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/upathtype.py +0 -0
  43. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/appconfig/validationconfig.py +0 -0
  44. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/__init__.py +0 -0
  45. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/buildbackend.py +0 -0
  46. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/markdownbackend.py +0 -0
  47. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/backends/mkdocsbackend.py +0 -0
  48. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/buildcollector.py +0 -0
  49. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/buildcontext.py +0 -0
  50. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/builders/__init__.py +0 -0
  51. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/cli/__init__.py +0 -0
  52. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/cli/richstate.py +0 -0
  53. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/commands/__init__.py +0 -0
  54. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/liveserver.py +0 -0
  55. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/__init__.py +0 -0
  56. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/cli_section.py +0 -0
  57. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/get_started_section.py +0 -0
  58. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/github_index.py +0 -0
  59. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/root.py +0 -0
  60. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/manual/use_cases_section.py +0 -0
  61. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/mkdefaultwebsite.py +0 -0
  62. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/paths.py +0 -0
  63. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/mkdocshelpers.py +0 -0
  64. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/plugin/rewriteloader.py +0 -0
  65. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/py.typed +0 -0
  66. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/resources/mkdocs_basic.yml +0 -0
  67. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/resources/timeline_data.toml +0 -0
  68. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes/telemetry.py +0 -0
  69. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/mkdocs_mknodes.sublime-project +0 -0
  70. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/overrides/_dummy.txt +0 -0
  71. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/overrides/partials/actions.html +0 -0
  72. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/pyproject.toml +0 -0
  73. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/tests/__init__.py +0 -0
  74. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/tests/conftest.py +0 -0
  75. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/tests/data/objects.inv +0 -0
  76. {mkdocs_mknodes-0.6.2 → mkdocs_mknodes-0.7.2}/tests/test_build.py +0 -0
  77. {mkdocs_mknodes-0.6.2 → 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
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: mkdocs-mknodes
3
- Version: 0.6.2
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
@@ -1,4 +1,4 @@
1
- __version__ = "0.6.2"
1
+ __version__ = "0.7.2"
2
2
 
3
3
 
4
4
  from .mkdefaultwebsite import MkDefaultWebsite
@@ -3,8 +3,7 @@ from __future__ import annotations
3
3
  from collections.abc import Callable
4
4
  import functools
5
5
  import ipaddress
6
- import os
7
- from typing import Annotated, Any, Self
6
+ from typing import Annotated, Any
8
7
 
9
8
  from mknodes.utils import classhelpers
10
9
  from pathspec import gitignore
@@ -18,9 +17,9 @@ from pydantic import (
18
17
  )
19
18
  from pydantic.functional_validators import BeforeValidator
20
19
  from pydantic_core import PydanticCustomError
21
- import yamling
22
20
 
23
21
  from mkdocs_mknodes.appconfig import jinjaconfig, themeconfig, validationconfig
22
+ from mkdocs_mknodes.appconfig.base import ConfigFile
24
23
 
25
24
 
26
25
  def validate_gitignore_patterns(pattern: list[str] | str) -> str:
@@ -71,7 +70,7 @@ class ExtraJavascript(BaseModel):
71
70
  defer: bool | None = None
72
71
 
73
72
 
74
- class AppConfig(BaseModel):
73
+ class AppConfig(ConfigFile):
75
74
  """The main configuration class for MkDocs projects.
76
75
 
77
76
  This class defines all available settings for customizing your documentation site.
@@ -85,18 +84,6 @@ class AppConfig(BaseModel):
85
84
  - `theme` configuration
86
85
  """
87
86
 
88
- @classmethod
89
- def from_yaml_file(cls, yaml_path: str | os.PathLike[str], **overrides: Any) -> Self:
90
- cfg = yamling.load_yaml_file(yaml_path)
91
- vals = {"config_file_path": str(yaml_path), **cfg, **overrides}
92
- return cls(**vals)
93
-
94
- config_file_path: str | None = Field(None, exclude=True)
95
- inherit: str | None = Field(None, description="", alias="INHERIT")
96
- """Define the parent for a configuration file.
97
-
98
- The path must be relative to the location of the primary file.
99
- """
100
87
  site_name: str = Field(...)
101
88
  """The primary title for your documentation project.
102
89
 
@@ -112,7 +99,7 @@ class AppConfig(BaseModel):
112
99
  ```
113
100
  """
114
101
 
115
- site_url: HttpUrl | None = Field(None)
102
+ site_url: str | None = Field(None)
116
103
  """The canonical URL for your documentation site.
117
104
 
118
105
  !!! info "Purpose"
@@ -679,7 +666,7 @@ class AppConfig(BaseModel):
679
666
  ```
680
667
  """
681
668
 
682
- exclude_docs: GitIgnorePatterns = Field(default_factory=list)
669
+ exclude_docs: GitIgnorePatterns = Field(default="")
683
670
  """Gitignore-style patterns for files to exclude from documentation.
684
671
 
685
672
  !!! info "Pattern Syntax"
@@ -702,7 +689,7 @@ class AppConfig(BaseModel):
702
689
  Patterns are relative to `docs_dir`
703
690
  """
704
691
 
705
- not_in_nav: GitIgnorePatterns = Field(str)
692
+ not_in_nav: GitIgnorePatterns = Field(default="")
706
693
  """Patterns for files that should not generate warnings when not in navigation.
707
694
 
708
695
  !!! info "Use Cases"
@@ -807,6 +794,11 @@ class AppConfig(BaseModel):
807
794
  case str():
808
795
  self.theme = themeconfig.ThemeConfig(name=theme, **kwargs)
809
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
+
810
802
  # @field_validator("theme", mode="before")
811
803
  # @classmethod
812
804
  # def validate_theme(cls, value: Any) -> ThemeConfig:
@@ -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)
@@ -4,12 +4,11 @@ import io
4
4
  import os
5
5
  from typing import Any
6
6
 
7
- from mkdocs.config import load_config
8
- from mkdocs.config.defaults import MkDocsConfig
9
7
  from mknodes.info import mkdocsconfigfile
10
8
  import yamling
11
9
 
12
10
  from mkdocs_mknodes import telemetry
11
+ from mkdocs_mknodes.plugin import mknodesconfig
13
12
 
14
13
 
15
14
  logger = telemetry.get_plugin_logger(__name__)
@@ -34,7 +33,7 @@ class ConfigBuilder:
34
33
 
35
34
  def build_mkdocs_config(
36
35
  self, site_dir: str | os.PathLike[str] | None = None, **kwargs: Any
37
- ) -> MkDocsConfig:
36
+ ) -> mknodesconfig.MkNodesConfig:
38
37
  cfg = self.configs[0]
39
38
  if site_dir:
40
39
  cfg["site_dir"] = site_dir
@@ -50,7 +49,7 @@ class ConfigBuilder:
50
49
  text = yamling.dump_yaml(dict(cfg))
51
50
  buffer = io.StringIO(text)
52
51
  buffer.name = cfg.path
53
- config = load_config(buffer, **kwargs)
52
+ config = mknodesconfig.MkNodesConfig.from_yaml(buffer, **kwargs)
54
53
 
55
54
  for k, v in config.items():
56
55
  logger.debug("%s: %s", k, v)
@@ -5,16 +5,15 @@ from __future__ import annotations
5
5
  from collections.abc import Collection, Sequence
6
6
  from datetime import UTC, datetime
7
7
  import os
8
- from typing import TYPE_CHECKING, Any
8
+ from typing import TYPE_CHECKING, Any, TypedDict
9
9
  from urllib.parse import urljoin, urlsplit
10
10
 
11
11
  import jinja2
12
12
  from jinja2.exceptions import TemplateNotFound
13
13
  from jinjarope import envtests, htmlfilters
14
14
  import logfire
15
- from mkdocs import exceptions
16
- from mkdocs.commands import build as mkdocs_build
17
- from mkdocs.structure.files import InclusionLevel
15
+ from mkdocs import exceptions, utils as mkdocs_utils
16
+ from mkdocs.structure.files import Files, InclusionLevel
18
17
  from mkdocs.structure.nav import Navigation, get_navigation
19
18
  from mkdocs.structure.pages import Page
20
19
  from mknodes.utils import pathhelpers
@@ -26,13 +25,27 @@ from mkdocs_mknodes.commands import utils
26
25
 
27
26
 
28
27
  if TYPE_CHECKING:
29
- from mkdocs.config.defaults import MkDocsConfig
30
- from mkdocs.structure.files import File, Files
28
+ from mkdocs.structure.files import File
29
+
30
+ from mkdocs_mknodes.plugin.mknodesconfig import MkNodesConfig
31
31
 
32
32
 
33
33
  logger = telemetry.get_plugin_logger(__name__)
34
34
 
35
35
 
36
+ class TemplateContext(TypedDict):
37
+ nav: Navigation
38
+ pages: Sequence[File]
39
+ base_url: str
40
+ extra_css: Sequence[str] # Do not use, prefer `config.extra_css`.
41
+ extra_javascript: Sequence[str] # Do not use, prefer `config.extra_javascript`.
42
+ mkdocs_version: str
43
+ mknodes_version: str
44
+ build_date_utc: datetime
45
+ config: MkNodesConfig
46
+ page: Page | None
47
+
48
+
36
49
  DRAFT_CONTENT = (
37
50
  '<div class="mkdocs-draft-marker" title="This page wont be included into the site.">'
38
51
  "DRAFT"
@@ -74,7 +87,7 @@ def build(
74
87
  @utils.handle_exceptions
75
88
  @utils.count_warnings
76
89
  def _build(
77
- config: MkDocsConfig,
90
+ config: MkNodesConfig,
78
91
  live_server_url: str | None = None,
79
92
  dirty: bool = False,
80
93
  ) -> None:
@@ -169,7 +182,7 @@ def _build(
169
182
 
170
183
 
171
184
  def _populate_page(
172
- page: Page, config: MkDocsConfig, files: Files, dirty: bool = False
185
+ page: Page, config: MkNodesConfig, files: Files, dirty: bool = False
173
186
  ) -> None:
174
187
  """Read page content from docs_dir and render Markdown."""
175
188
  config._current_page = page
@@ -213,7 +226,7 @@ def _populate_page(
213
226
 
214
227
  def _build_page(
215
228
  page: Page,
216
- config: MkDocsConfig,
229
+ config: MkNodesConfig,
217
230
  doc_files: Sequence[File],
218
231
  nav: Navigation,
219
232
  env: jinja2.Environment,
@@ -229,11 +242,11 @@ def _build_page(
229
242
  logger.debug("Building page %s", page.file.src_uri)
230
243
  # Activate page. Signals to theme that this is the current page.
231
244
  page.active = True
232
- ctx = mkdocs_build.get_context(nav, doc_files, config, page)
245
+ ctx = get_context(nav, doc_files, config, page)
233
246
  # Allow 'template:' override in md source files.
234
247
  template = env.get_template(page.meta.get("template", "main.html"))
235
248
  # Run `page_context` plugin events.
236
- ctx = config.plugins.on_page_context(ctx, page=page, config=config, nav=nav)
249
+ ctx = config.plugins.on_page_context(ctx, page=page, config=config, nav=nav) # type: ignore
237
250
 
238
251
  if excluded:
239
252
  page.content = DRAFT_CONTENT + (page.content or "")
@@ -267,7 +280,7 @@ def _build_template(
267
280
  name: str,
268
281
  template: jinja2.Template,
269
282
  files: Files,
270
- config: MkDocsConfig,
283
+ config: MkNodesConfig,
271
284
  nav: Navigation,
272
285
  ) -> str:
273
286
  """Return rendered output for given template as a string."""
@@ -281,8 +294,8 @@ def _build_template(
281
294
  base_url = urlsplit(config.site_url or "/").path
282
295
  else:
283
296
  base_url = htmlfilters.relative_url_mkdocs(".", name)
284
- context = mkdocs_build.get_context(nav, files, config, base_url=base_url)
285
- ctx = config.plugins.on_template_context(context, template_name=name, config=config)
297
+ context = get_context(nav, files, config, base_url=base_url)
298
+ ctx = config.plugins.on_template_context(context, template_name=name, config=config) # type: ignore
286
299
  output = template.render(ctx)
287
300
  return config.plugins.on_post_template(output, template_name=name, config=config)
288
301
 
@@ -291,7 +304,7 @@ def _build_theme_template(
291
304
  template_name: str,
292
305
  env: jinja2.Environment,
293
306
  files: Files,
294
- config: MkDocsConfig,
307
+ config: MkNodesConfig,
295
308
  nav: Navigation,
296
309
  ) -> None:
297
310
  """Build a template using the theme environment."""
@@ -317,7 +330,7 @@ def _build_theme_template(
317
330
 
318
331
 
319
332
  def _build_extra_template(
320
- template_name: str, files: Files, config: MkDocsConfig, nav: Navigation
333
+ template_name: str, files: Files, config: MkNodesConfig, nav: Navigation
321
334
  ):
322
335
  """Build user templates which are not part of the theme."""
323
336
  logger.debug("Building extra template: %s", template_name)
@@ -359,6 +372,46 @@ def get_build_timestamp(*, pages: Collection[Page] | None = None) -> int:
359
372
  return int(dt.timestamp())
360
373
 
361
374
 
375
+ def get_context(
376
+ nav: Navigation,
377
+ files: Sequence[File] | Files,
378
+ config: MkNodesConfig,
379
+ page: Page | None = None,
380
+ base_url: str = "",
381
+ ) -> TemplateContext:
382
+ """Return the template context for a given page or template."""
383
+ if page is not None:
384
+ base_url = mkdocs_utils.get_relative_url(".", page.url)
385
+
386
+ extra_javascript = [
387
+ mkdocs_utils.normalize_url(str(script), page, base_url)
388
+ for script in config.extra_javascript
389
+ ]
390
+ extra_css = [
391
+ mkdocs_utils.normalize_url(path, page, base_url) for path in config.extra_css
392
+ ]
393
+
394
+ if isinstance(files, Files):
395
+ files = files.documentation_pages()
396
+
397
+ import mkdocs
398
+
399
+ import mkdocs_mknodes
400
+
401
+ return TemplateContext(
402
+ nav=nav,
403
+ pages=files,
404
+ base_url=base_url,
405
+ extra_css=extra_css,
406
+ extra_javascript=extra_javascript,
407
+ mknodes_version=mkdocs_mknodes.__version__,
408
+ mkdocs_version=mkdocs.__version__,
409
+ build_date_utc=utils.get_build_datetime(),
410
+ config=config,
411
+ page=page,
412
+ )
413
+
414
+
362
415
  if __name__ == "__main__":
363
416
  from mkdocs_mknodes.appconfig import appconfig
364
417
 
@@ -10,17 +10,17 @@ from typing import TYPE_CHECKING, Any, Literal
10
10
  from urllib.parse import urlsplit
11
11
 
12
12
  # from mkdocs.commands import serve as serve_
13
- from mkdocs.config import load_config
14
13
  from mknodes.info import mkdocsconfigfile
15
14
  from mknodes.utils import log
16
15
  import yamling
17
16
 
18
17
  from mkdocs_mknodes import liveserver, paths
19
18
  from mkdocs_mknodes.commands import build_page
19
+ from mkdocs_mknodes.plugin import mknodesconfig
20
20
 
21
21
 
22
22
  if TYPE_CHECKING:
23
- from mkdocs.config.defaults import MkDocsConfig
23
+ pass
24
24
 
25
25
  logger = log.get_logger(__name__)
26
26
 
@@ -75,7 +75,7 @@ def serve_node(node, repo_path: str = "."):
75
75
 
76
76
 
77
77
  @contextlib.contextmanager
78
- def catch_exceptions(config: MkDocsConfig):
78
+ def catch_exceptions(config: mknodesconfig.MkNodesConfig):
79
79
  """Context manager used to clean up in case of build error.
80
80
 
81
81
  Args:
@@ -90,7 +90,7 @@ def catch_exceptions(config: MkDocsConfig):
90
90
 
91
91
 
92
92
  def _serve(
93
- config_file: str | None = None,
93
+ config_file: str | None | yamling.YAMLInput = None,
94
94
  livereload: bool = True,
95
95
  build_type: Literal["clean", "dirty"] | None = None,
96
96
  watch_theme: bool = False,
@@ -114,11 +114,15 @@ def _serve(
114
114
  watch = watch or []
115
115
  site_dir = pathlib.Path(tempfile.mkdtemp(prefix="mkdocs_"))
116
116
 
117
- def mount_path(config: MkDocsConfig) -> str:
117
+ def mount_path(config: mknodesconfig.MkNodesConfig) -> str:
118
118
  return urlsplit(config.site_url or "/").path
119
119
 
120
- def get_config() -> MkDocsConfig:
121
- config = load_config(config_file=config_file, site_dir=str(site_dir), **kwargs)
120
+ def get_config() -> mknodesconfig.MkNodesConfig:
121
+ config = mknodesconfig.MkNodesConfig.from_yaml(
122
+ config_file=config_file, # type: ignore[arg-type]
123
+ site_dir=str(site_dir),
124
+ **kwargs,
125
+ )
122
126
  config.watch.extend(watch)
123
127
  config.site_url = f"http://{config.dev_addr}{mount_path(config)}"
124
128
  return config
@@ -133,7 +137,7 @@ def _serve(
133
137
  suffix = mount_path(config).lstrip("/").rstrip("/")
134
138
  url = None if is_clean else f"http://{host}:{port}/{suffix}/"
135
139
 
136
- def builder(config: MkDocsConfig | None = None):
140
+ def builder(config: mknodesconfig.MkNodesConfig | None = None):
137
141
  logger.info("Building documentation...")
138
142
  if config is None:
139
143
  config = get_config()
@@ -24,7 +24,7 @@ from mkdocs_mknodes import telemetry
24
24
 
25
25
 
26
26
  if TYPE_CHECKING:
27
- from mkdocs.config.defaults import MkDocsConfig
27
+ from mkdocs_mknodes.plugin.mknodesconfig import MkNodesConfig
28
28
 
29
29
 
30
30
  logger = telemetry.get_plugin_logger(__name__)
@@ -58,7 +58,7 @@ class CountHandler(logging.NullHandler):
58
58
 
59
59
  def count_warnings(fn: Callable[..., T]) -> Callable[..., T]:
60
60
  @functools.wraps(fn)
61
- def wrapped(config: MkDocsConfig, *args, **kwargs) -> T:
61
+ def wrapped(config: MkNodesConfig, *args, **kwargs) -> T:
62
62
  start = time.monotonic()
63
63
  warning_counter = CountHandler()
64
64
  warning_counter.setLevel(logging.WARNING)
@@ -81,7 +81,7 @@ def count_warnings(fn: Callable[..., T]) -> Callable[..., T]:
81
81
 
82
82
  def handle_exceptions(fn: Callable[..., T]) -> Callable[..., T]:
83
83
  @functools.wraps(fn)
84
- def wrapped(config: MkDocsConfig, *args, **kwargs) -> T:
84
+ def wrapped(config: MkNodesConfig, *args, **kwargs) -> T:
85
85
  try:
86
86
  return fn(config, *args, **kwargs)
87
87
  except Exception as e:
@@ -98,7 +98,7 @@ def handle_exceptions(fn: Callable[..., T]) -> Callable[..., T]:
98
98
  return wrapped
99
99
 
100
100
 
101
- def set_exclusions(files: Iterable[File], config: MkDocsConfig) -> None:
101
+ def set_exclusions(files: Iterable[File], config: MkNodesConfig) -> None:
102
102
  """Re-calculate which files are excluded, based on the patterns in the config."""
103
103
  exclude: pathspec.gitignore.GitIgnoreSpec | None = config.get("exclude_docs")
104
104
  exclude = _default_exclude + exclude if exclude else _default_exclude
@@ -119,7 +119,7 @@ def set_exclusions(files: Iterable[File], config: MkDocsConfig) -> None:
119
119
  file.inclusion = InclusionLevel.INCLUDED
120
120
 
121
121
 
122
- def get_files(config: MkDocsConfig) -> Files:
122
+ def get_files(config: MkNodesConfig) -> Files:
123
123
  """Walk the `docs_dir` and return a Files collection."""
124
124
  files: list[File] = []
125
125
  conflicting_files: list[tuple[File, File]] = []
@@ -4,7 +4,6 @@ from collections.abc import Iterator, Mapping
4
4
  import contextlib
5
5
  from datetime import datetime
6
6
  import functools
7
- import io
8
7
  import os
9
8
  import pathlib
10
9
  import sys
@@ -12,13 +11,12 @@ from typing import Any, TextIO
12
11
  from urllib import parse
13
12
 
14
13
  import jinjarope
15
- from mkdocs.__main__ import get_deps_command
16
- from mkdocs.config.defaults import MkDocsConfig
17
14
  from mknodes.info import contexts
18
15
  from mknodes.mdlib import mdconverter
19
16
  from mknodes.utils import pathhelpers, reprhelpers
20
17
 
21
18
  from mkdocs_mknodes import telemetry
19
+ from mkdocs_mknodes.plugin.mknodesconfig import MkNodesConfig
22
20
 
23
21
 
24
22
  logger = telemetry.get_plugin_logger(__name__)
@@ -80,7 +78,7 @@ def load_config(
80
78
  *,
81
79
  config_file_path: str | None = None,
82
80
  **kwargs,
83
- ) -> MkDocsConfig:
81
+ ) -> MkNodesConfig:
84
82
  """Load the configuration for a given file object or name.
85
83
 
86
84
  The config_file can either be a file object, string or None. If it is None
@@ -95,7 +93,7 @@ def load_config(
95
93
 
96
94
  if config_file_path is None and fd is not sys.stdin.buffer:
97
95
  config_file_path = getattr(fd, "name", None)
98
- cfg = MkDocsConfig(config_file_path=config_file_path)
96
+ cfg = MkNodesConfig(config_file_path=config_file_path)
99
97
  cfg.load_file(fd)
100
98
 
101
99
  # Then load the options to overwrite anything in the config.
@@ -126,8 +124,8 @@ class Config:
126
124
  config: MkDocs config
127
125
  """
128
126
  match config:
129
- case MkDocsConfig():
130
- self._config: MkDocsConfig = config
127
+ case MkNodesConfig():
128
+ self._config: MkNodesConfig = config
131
129
  case Mapping():
132
130
  self._config = load_config(config)
133
131
  case str() | os.PathLike() as path:
@@ -221,14 +219,6 @@ class Config:
221
219
  cfg.loader |= jinjarope.FileSystemLoader(self.docs_dir)
222
220
  return cfg
223
221
 
224
- def get_install_candidates(self) -> list[str]:
225
- """Return a list of installation candidates for this config."""
226
- path = "https://raw.githubusercontent.com/mkdocs/catalog/main/projects.yaml"
227
- buffer = io.StringIO()
228
- with contextlib.redirect_stdout(buffer):
229
- get_deps_command(path, self._config.config_file_path)
230
- return [i for i in buffer.getvalue().split("\n") if i]
231
-
232
222
  def add_js(
233
223
  self,
234
224
  path: str,
@@ -16,7 +16,7 @@ import jinjarope
16
16
 
17
17
  from mkdocs_mknodes import buildcollector, mkdocsconfig, telemetry
18
18
  from mkdocs_mknodes.backends import markdownbackend, mkdocsbackend
19
- from mkdocs_mknodes.plugin import pluginconfig, rewriteloader
19
+ from mkdocs_mknodes.plugin import mknodesconfig, pluginconfig, rewriteloader
20
20
 
21
21
  if TYPE_CHECKING:
22
22
  import jinja2
@@ -38,9 +38,19 @@ class MkNodesPlugin(BasePlugin[pluginconfig.PluginConfig]):
38
38
  super().__init__(**kwargs)
39
39
  self.link_replacer = linkreplacer.LinkReplacer()
40
40
  logger.debug("Finished initializing plugin")
41
+ self.build_folder = None
42
+ self._dir = None
43
+ self.linkprovider = None
44
+ self.theme = None
45
+ self.folderinfo = None
46
+ self.context = None
47
+ self.root = None
41
48
 
42
49
  def on_startup(self, *, command: CommandStr, dirty: bool):
43
50
  """Activates new-style MkDocs plugin lifecycle."""
51
+
52
+ def on_config(self, config: mknodesconfig.MkNodesConfig): # type: ignore
53
+ """Create the project based on MkDocs config."""
44
54
  if self.config.build_folder:
45
55
  self.build_folder = pathlib.Path(self.config.build_folder)
46
56
  else:
@@ -51,8 +61,6 @@ class MkNodesPlugin(BasePlugin[pluginconfig.PluginConfig]):
51
61
  self.build_folder = pathlib.Path(self._dir.name)
52
62
  logger.debug("Creating temporary dir %s", self._dir.name)
53
63
 
54
- def on_config(self, config: MkDocsConfig):
55
- """Create the project based on MkDocs config."""
56
64
  if not self.config.build_fn:
57
65
  return
58
66
  self.linkprovider = linkprovider.LinkProvider(
@@ -78,7 +86,7 @@ class MkNodesPlugin(BasePlugin[pluginconfig.PluginConfig]):
78
86
  env_config=self.config.get_jinja_config(),
79
87
  )
80
88
 
81
- def on_files(self, files: Files, *, config: MkDocsConfig) -> Files:
89
+ def on_files(self, files: Files, *, config: mknodesconfig.MkNodesConfig) -> Files: # type: ignore
82
90
  """Create the node tree and write files to build folder.
83
91
 
84
92
  In this step we aggregate all files and info we need to build the website.
@@ -202,7 +210,7 @@ class MkNodesPlugin(BasePlugin[pluginconfig.PluginConfig]):
202
210
  """During this phase links get replaced and `jinja2` stuff get rendered."""
203
211
  return self.link_replacer.replace(markdown, page.file.src_uri)
204
212
 
205
- def on_post_build(self, *, config: MkDocsConfig) -> None:
213
+ def on_post_build(self, *, config: mknodesconfig.MkNodesConfig) -> None: # type: ignore
206
214
  """Delete the temporary template files."""
207
215
  if not config.theme.custom_dir or not self.config.build_fn:
208
216
  return
@@ -7,6 +7,7 @@ from mkdocs.config.defaults import MkDocsConfig
7
7
  from mkdocs.structure import files as files_, nav, pages
8
8
 
9
9
  from mkdocs_mknodes import mkdocsconfig, telemetry
10
+ from mkdocs_mknodes.plugin.mknodesconfig import MkNodesConfig
10
11
 
11
12
 
12
13
  if TYPE_CHECKING:
@@ -18,7 +19,7 @@ logger = telemetry.get_plugin_logger(__name__)
18
19
  class MkDocsPage(pages.Page):
19
20
  """MkPage-based Mkocs-Page subclass."""
20
21
 
21
- def __init__(self, mkpage: mk.MkPage, file: files_.File, config: MkDocsConfig):
22
+ def __init__(self, mkpage: mk.MkPage, file: files_.File, config: MkNodesConfig):
22
23
  self.mkpage = mkpage
23
24
  super().__init__(title=self.mkpage.title, file=file, config=config)
24
25
 
@@ -32,7 +33,11 @@ class MkDocsPage(pages.Page):
32
33
  class MkDocsBuilder:
33
34
  def __init__(
34
35
  self,
35
- config: mkdocsconfig.Config | MkDocsConfig | str | os.PathLike[str] | None = None,
36
+ config: mkdocsconfig.Config
37
+ | MkNodesConfig
38
+ | str
39
+ | os.PathLike[str]
40
+ | None = None,
36
41
  ):
37
42
  """Constructor.
38
43
 
@@ -42,7 +47,7 @@ class MkDocsBuilder:
42
47
  match config:
43
48
  case mkdocsconfig.Config():
44
49
  self._config = config._config
45
- case MkDocsConfig():
50
+ case MkNodesConfig():
46
51
  self._config = config
47
52
  case _:
48
53
  self._config = mkdocsconfig.Config(config)._config
@@ -15,11 +15,11 @@ from typing import Any, Self, TextIO
15
15
  from urllib import parse
16
16
 
17
17
  import jinjarope
18
- from mkdocs.__main__ import get_deps_command
19
18
  from mkdocs.config import config_options as c, defaults
20
19
  from mknodes.info import contexts
21
20
  from mknodes.mdlib import mdconverter
22
21
  from mknodes.utils import classhelpers
22
+ import upath
23
23
  import yamling
24
24
 
25
25
 
@@ -71,7 +71,7 @@ def _open_config_file(
71
71
  class MkNodesConfig(defaults.MkDocsConfig):
72
72
  @classmethod
73
73
  @functools.cache
74
- def from_yaml_file(
74
+ def from_yaml(
75
75
  cls,
76
76
  config_file: str | TextIO | None = None,
77
77
  *,
@@ -93,7 +93,7 @@ class MkNodesConfig(defaults.MkDocsConfig):
93
93
  if config_file_path is None and fd is not sys.stdin.buffer:
94
94
  config_file_path = getattr(fd, "name", None)
95
95
  cfg = cls(config_file_path=config_file_path)
96
- dct = yamling.load_yaml(fd)
96
+ dct = yamling.load_yaml(fd, resolve_inherit=True)
97
97
  cfg.load_dict(dct)
98
98
  # Then load the options to overwrite anything in the config.
99
99
  cfg.load_dict(options)
@@ -112,6 +112,17 @@ class MkNodesConfig(defaults.MkDocsConfig):
112
112
  raise SystemExit(msg)
113
113
  return cfg
114
114
 
115
+ @classmethod
116
+ def from_yaml_file(
117
+ cls,
118
+ file: str | os.PathLike[str],
119
+ config_file_path: str | None = None,
120
+ ) -> Self:
121
+ # cfg = yamling.load_yaml_file(file, resolve_inherit=True)
122
+ config_str = upath.UPath(file).read_text()
123
+ str_io = io.StringIO(config_str)
124
+ return cls.from_yaml(str_io, config_file_path=config_file_path)
125
+
115
126
  build_fn = c.Type(str, default="mkdocs_mknodes:parse")
116
127
  """Path to the build script / callable.
117
128
 
@@ -307,14 +318,6 @@ class MkNodesConfig(defaults.MkDocsConfig):
307
318
  rel_path = edit_path
308
319
  return parse.urljoin(base_url, rel_path)
309
320
 
310
- def get_install_candidates(self) -> list[str]:
311
- """Return a list of installation candidates for this config."""
312
- path = "https://raw.githubusercontent.com/mkdocs/catalog/main/projects.yaml"
313
- buffer = io.StringIO()
314
- with contextlib.redirect_stdout(buffer):
315
- get_deps_command(path, super().config_file_path)
316
- return [i for i in buffer.getvalue().split("\n") if i]
317
-
318
321
  def add_js(
319
322
  self,
320
323
  path: str,
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from collections.abc import Callable
6
6
  import functools
7
+ from typing import Any
7
8
 
8
9
  import jinjarope
9
10
  from mkdocs.config import base, config_options as c
@@ -127,7 +128,7 @@ class PluginConfig(base.Config):
127
128
  llm_model_name = c.Optional(c.Type(str))
128
129
  """LLM model name to use."""
129
130
 
130
- def get_builder(self) -> Callable:
131
+ def get_builder(self) -> Callable[..., Any]:
131
132
  build_fn = classhelpers.to_callable(self.build_fn)
132
133
  build_kwargs = self.kwargs or {}
133
134
  return functools.partial(build_fn, **build_kwargs)
@@ -1,68 +0,0 @@
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 mkdocs 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
File without changes
File without changes
File without changes