mkdocs-mknodes 0.0.2__py3-none-any.whl

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 (40) hide show
  1. mkdocs_mknodes/__init__.py +1 -0
  2. mkdocs_mknodes/buildcollector.py +167 -0
  3. mkdocs_mknodes/cli/__init__.py +194 -0
  4. mkdocs_mknodes/manual/__init__.py +13 -0
  5. mkdocs_mknodes/manual/cli_section.py +37 -0
  6. mkdocs_mknodes/manual/dev_section.py +70 -0
  7. mkdocs_mknodes/manual/github_index.py +17 -0
  8. mkdocs_mknodes/manual/internals_section.py +74 -0
  9. mkdocs_mknodes/manual/multi_project.py +19 -0
  10. mkdocs_mknodes/manual/root.py +77 -0
  11. mkdocs_mknodes/manual/use_cases_section.py +34 -0
  12. mkdocs_mknodes/mkdocsconfig.py +141 -0
  13. mkdocs_mknodes/paths.py +11 -0
  14. mkdocs_mknodes/plugin/__init__.py +179 -0
  15. mkdocs_mknodes/plugin/build_page.py +165 -0
  16. mkdocs_mknodes/plugin/buildbackend.py +45 -0
  17. mkdocs_mknodes/plugin/linkreplacer.py +49 -0
  18. mkdocs_mknodes/plugin/markdownbackend.py +37 -0
  19. mkdocs_mknodes/plugin/mkdocsbackend.py +184 -0
  20. mkdocs_mknodes/plugin/mkdocsbuilder.py +127 -0
  21. mkdocs_mknodes/plugin/mkdocshelpers.py +24 -0
  22. mkdocs_mknodes/plugin/pluginconfig.py +45 -0
  23. mkdocs_mknodes/plugin/serve.py +228 -0
  24. mkdocs_mknodes/resources/build_process.jinja +55 -0
  25. mkdocs_mknodes/resources/cli_index.jinja +15 -0
  26. mkdocs_mknodes/resources/material_css.jinja +88 -0
  27. mkdocs_mknodes/resources/material_css_extra.jinja +223 -0
  28. mkdocs_mknodes/resources/mkclasspage.jinja +11 -0
  29. mkdocs_mknodes/resources/mkdocs_css.jinja +7 -0
  30. mkdocs_mknodes/resources/modulepage.md +11 -0
  31. mkdocs_mknodes/resources/python_objects.inv +0 -0
  32. mkdocs_mknodes/resources/requirements.md +31 -0
  33. mkdocs_mknodes/resources/use_case_by_config.jinja +10 -0
  34. mkdocs_mknodes/resources/use_case_default_website.jinja +10 -0
  35. mkdocs_mknodes/resources/use_cases_index.jinja +46 -0
  36. mkdocs_mknodes-0.0.2.dist-info/METADATA +96 -0
  37. mkdocs_mknodes-0.0.2.dist-info/RECORD +40 -0
  38. mkdocs_mknodes-0.0.2.dist-info/WHEEL +4 -0
  39. mkdocs_mknodes-0.0.2.dist-info/entry_points.txt +5 -0
  40. mkdocs_mknodes-0.0.2.dist-info/licenses/LICENSE +22 -0
@@ -0,0 +1,184 @@
1
+ from __future__ import annotations
2
+
3
+ import collections
4
+ import os
5
+ import pathlib
6
+
7
+ import markdown
8
+
9
+ from mkdocs.config import config_options
10
+ from mkdocs.config.defaults import MkDocsConfig
11
+ from mkdocs.plugins import get_plugin_logger
12
+ from mkdocs.structure import files as files_
13
+ from mknodes import mkdocsconfig, paths
14
+ from mknodes.utils import mergehelpers, pathhelpers, resources
15
+
16
+ from mkdocs_mknodes.plugin import buildbackend, mkdocsbuilder, mkdocshelpers
17
+
18
+
19
+ logger = get_plugin_logger(__name__)
20
+
21
+
22
+ class MkDocsBackend(buildbackend.BuildBackend):
23
+ def __init__(
24
+ self,
25
+ files: files_.Files | None = None,
26
+ config: mkdocsconfig.Config | MkDocsConfig | str | os.PathLike | None = None,
27
+ directory: str | os.PathLike | None = None,
28
+ ):
29
+ match config:
30
+ case mkdocsconfig.Config():
31
+ self._config = config._config
32
+ case MkDocsConfig():
33
+ self._config = config
34
+ case _:
35
+ self._config = mkdocsconfig.Config(config)._config
36
+ self.directory = pathlib.Path(directory or ".")
37
+ files_map = {pathlib.PurePath(f.src_path).as_posix(): f for f in files or []}
38
+ self._mk_files: collections.ChainMap[str, files_.File] = collections.ChainMap(
39
+ {},
40
+ files_map,
41
+ )
42
+ self.builder = mkdocsbuilder.MkDocsBuilder(self._config)
43
+
44
+ def _get_parser(self) -> markdown.Markdown:
45
+ """Return a markdown instance based on given config."""
46
+ return markdown.Markdown(
47
+ extensions=self._config.markdown_extensions,
48
+ extension_configs=self._config.mdx_configs,
49
+ )
50
+
51
+ @property
52
+ def files(self) -> files_.Files:
53
+ """Access the files as they currently are, as a MkDocs [Files][] collection.
54
+
55
+ [Files]: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/files.py
56
+ """
57
+ files = sorted(self._mk_files.values(), key=mkdocshelpers.file_sorter)
58
+ return files_.Files(files)
59
+
60
+ def collect_files(self, files):
61
+ for k, v in files.items():
62
+ logger.debug("%s: Writing file to %r", type(self).__name__, str(k))
63
+ path = pathlib.Path(k).as_posix()
64
+ # self._files[path] = v
65
+ self._write_file(path, v)
66
+
67
+ def collect_assets(self, assets):
68
+ for asset in assets:
69
+ if asset.target_dir == "docs_dir":
70
+ abs_path = pathlib.Path(self._config.docs_dir) / asset.filename
71
+ logger.info("Writing asset %s...", abs_path)
72
+ pathhelpers.write_file(asset.content, abs_path)
73
+ else:
74
+ raise ValueError(asset.target_dir)
75
+
76
+ def collect_css(self, css_files):
77
+ for css in css_files:
78
+ if isinstance(css, resources.CSSFile):
79
+ file_path = paths.RESOURCES / css
80
+ css_text = file_path.read_text()
81
+ path = f"{hash(css_text)}.css"
82
+ self.add_css_file(path, css_text)
83
+ elif isinstance(css, resources.CSSText):
84
+ self.add_css_file(css.filename, css.content)
85
+ else:
86
+ logger.debug("Adding remote CSS file %s", css)
87
+ self._config.extra_css.append(str(css))
88
+
89
+ def collect_js_links(self, js_links):
90
+ for file in js_links:
91
+ logger.debug("Adding remote JS file %s", str(file))
92
+ val = config_options.ExtraScriptValue(str(file))
93
+ val.async_ = file.async_
94
+ val.defer = file.defer
95
+ val.type = file.typ
96
+ self._config.extra_javascript.append(val)
97
+
98
+ def collect_js_files(self, js_files):
99
+ for file in js_files:
100
+ file_path = paths.RESOURCES / str(file)
101
+ js_text = file_path.read_text()
102
+ path = (pathlib.Path("assets") / f"{hash(js_text)}.css").as_posix()
103
+ val = config_options.ExtraScriptValue(str(path))
104
+ val.async_ = file.async_
105
+ val.defer = file.defer
106
+ val.type = file.typ
107
+ self._config.extra_javascript.append(path)
108
+ abs_path = pathlib.Path(self._config.site_dir) / path
109
+ logger.info("Registering js file %s...", abs_path)
110
+ pathhelpers.write_file(js_text, abs_path)
111
+
112
+ def collect_extensions(self, extensions):
113
+ if extensions:
114
+ for ext_name in extensions:
115
+ if ext_name not in self._config.markdown_extensions:
116
+ logger.info("Adding %s to extensions", ext_name)
117
+ self._config.markdown_extensions.append(ext_name)
118
+ self._config.mdx_configs = mergehelpers.merge_dicts(
119
+ self._config.mdx_configs,
120
+ extensions,
121
+ )
122
+
123
+ def collect_templates(self, templates):
124
+ if not self._config.theme.custom_dir:
125
+ logger.warning("Cannot write template. No custom_dir set in config.")
126
+ return
127
+ path = pathlib.Path(self._config.theme.custom_dir)
128
+ for template in templates:
129
+ md = self._get_parser()
130
+ if html := template.build_html(md):
131
+ target_path = path / template.filename
132
+ logger.info("Creating %s...", target_path.as_posix())
133
+ pathhelpers.write_file(html, target_path)
134
+
135
+ def _write_file(self, path: str | os.PathLike, content: str | bytes):
136
+ path = pathlib.PurePath(path).as_posix()
137
+ file_for_path = self.builder.get_file(path, src_dir=self.directory)
138
+ new_path = pathlib.Path(file_for_path.abs_src_path)
139
+ target_path = None
140
+ if path not in self._mk_files:
141
+ new_path.parent.mkdir(exist_ok=True, parents=True)
142
+ self._mk_files[path] = file_for_path
143
+ target_path = new_path
144
+
145
+ f = self._mk_files[path]
146
+ source_path = pathlib.Path(f.abs_src_path)
147
+ if source_path != new_path:
148
+ self._mk_files[path] = file_for_path
149
+ pathhelpers.copy(source_path, new_path)
150
+ target_path = new_path
151
+ pathhelpers.write_file(content, target_path or source_path)
152
+
153
+ def add_css_file(self, filename: str | os.PathLike, css: str):
154
+ """Register a css file.
155
+
156
+ Writes file to build assets folder and registers extra_css in config
157
+
158
+ Arguments:
159
+ filename: Filename to write
160
+ css: file content
161
+ """
162
+ path = (pathlib.Path("assets") / filename).as_posix()
163
+ self._config.extra_css.append(path)
164
+ abs_path = pathlib.Path(self._config.site_dir) / path
165
+ logger.info("Registering css file %s...", abs_path)
166
+ pathhelpers.write_file(css, abs_path)
167
+
168
+
169
+ if __name__ == "__main__":
170
+ backend = MkDocsBackend()
171
+
172
+ from mknodes import project
173
+ from mknodes.theme import theme as theme_
174
+
175
+ skin = theme_.Theme("material")
176
+ proj = project.Project(
177
+ base_url="",
178
+ use_directory_urls=True,
179
+ theme=skin,
180
+ repo=".",
181
+ build_fn=paths.DEFAULT_BUILD_FN,
182
+ clone_depth=1,
183
+ )
184
+ proj.build()
@@ -0,0 +1,127 @@
1
+ from __future__ import annotations
2
+
3
+ import os
4
+
5
+ from mkdocs.config.defaults import MkDocsConfig
6
+ from mkdocs.plugins import get_plugin_logger
7
+ from mkdocs.structure import files as files_, nav, pages
8
+ from mknodes import mkdocsconfig
9
+
10
+ from mkdocs_mknodes.plugin import buildbackend
11
+
12
+
13
+ logger = get_plugin_logger(__name__)
14
+
15
+
16
+ class MkDocsPage(pages.Page):
17
+ def __init__(self, mkpage, file, config: MkDocsConfig):
18
+ self.mkpage = mkpage
19
+ super().__init__(title=self.mkpage.title, file=file, config=config)
20
+
21
+ def read_source(self, config: MkDocsConfig):
22
+ self.meta = self.mkpage.metadata
23
+ self.mkpage.metadata = {}
24
+ self.markdown = str(self.mkpage)
25
+ self.mkpage.metadata = self.meta
26
+
27
+
28
+ class MkDocsBuilder(buildbackend.BuildBackend):
29
+ def __init__(
30
+ self,
31
+ config: mkdocsconfig.Config | MkDocsConfig | str | os.PathLike | None = None,
32
+ ):
33
+ match config:
34
+ case mkdocsconfig.Config():
35
+ self._config = config._config
36
+ case MkDocsConfig():
37
+ self._config = config
38
+ case _:
39
+ self._config = mkdocsconfig.Config(config)._config
40
+ self.mk_files = files_.Files([])
41
+
42
+ def get_file(
43
+ self,
44
+ path: str | os.PathLike,
45
+ src_dir: str | os.PathLike | None = None,
46
+ dest_dir: str | os.PathLike | None = None,
47
+ inclusion_level: files_.InclusionLevel = files_.InclusionLevel.UNDEFINED,
48
+ ) -> files_.File:
49
+ """Return a MkDocs File for given path.
50
+
51
+ Arguments:
52
+ path: path to get a File object for (relative to src_dir)
53
+ src_dir: Source directory. If None, docs_dir is used.
54
+ dest_dir: Target directory. If None, site_dir is used.
55
+ inclusion_level: Inclusion level of new file
56
+ """
57
+ new_f = files_.File(
58
+ os.fspath(path),
59
+ src_dir=str(src_dir) if src_dir else self._config.docs_dir,
60
+ dest_dir=str(dest_dir) if dest_dir else self._config.site_dir,
61
+ use_directory_urls=self._config.use_directory_urls,
62
+ inclusion=inclusion_level,
63
+ )
64
+ self.mk_files.append(new_f)
65
+ new_f.generated_by = "mknodes" # type: ignore
66
+ return new_f
67
+
68
+ def get_section_page(
69
+ self,
70
+ title: str,
71
+ path: str | os.PathLike,
72
+ children: list[pages.Page | nav.Section | nav.Link],
73
+ inclusion_level: files_.InclusionLevel = files_.InclusionLevel.UNDEFINED,
74
+ ) -> pages.Page:
75
+ import mkdocs_section_index
76
+
77
+ file = self.get_file(path, inclusion_level=inclusion_level)
78
+ return mkdocs_section_index.SectionPage(
79
+ title=title,
80
+ file=file,
81
+ config=self._config,
82
+ children=children,
83
+ )
84
+
85
+ def get_page(
86
+ self,
87
+ mkpage,
88
+ run_event_hooks: bool = False,
89
+ ) -> pages.Page:
90
+ file = self.get_file(
91
+ mkpage.resolved_file_path,
92
+ inclusion_level=files_.InclusionLevel.UNDEFINED,
93
+ )
94
+ page = MkDocsPage(mkpage, file, self._config)
95
+
96
+ if run_event_hooks:
97
+ self._config._current_page = page
98
+ page = self._config.plugins.on_pre_page(
99
+ page,
100
+ config=self._config,
101
+ files=self.mk_files,
102
+ )
103
+ page.read_source(self._config)
104
+ page.markdown = self._config.plugins.on_page_markdown(
105
+ page.markdown or "",
106
+ page=page,
107
+ config=self._config,
108
+ files=self.mk_files,
109
+ )
110
+ page.render(self._config, self.mk_files)
111
+ page.content = self._config.plugins.on_page_content(
112
+ page.content or "",
113
+ page=page,
114
+ config=self._config,
115
+ files=self.mk_files,
116
+ )
117
+
118
+ self._config._current_page = None
119
+
120
+ return page
121
+
122
+ def get_nav(self) -> nav.Navigation:
123
+ return nav.get_navigation(self.mk_files, self._config)
124
+
125
+
126
+ if __name__ == "__main__":
127
+ cfg = MkDocsBuilder()
@@ -0,0 +1,24 @@
1
+ """The Mkdocs Plugin."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pathlib
6
+
7
+ from mkdocs.plugins import get_plugin_logger
8
+ from mkdocs.structure.files import File, Files
9
+
10
+
11
+ logger = get_plugin_logger(__name__)
12
+
13
+
14
+ def file_sorter(f: File):
15
+ parts = pathlib.PurePath(f.src_path).parts
16
+ return tuple(
17
+ chr(f.name != "index" if i == len(parts) - 1 else 2) + p
18
+ for i, p in enumerate(parts)
19
+ )
20
+
21
+
22
+ def merge_files(*files: Files) -> Files:
23
+ file_list = [i for j in files for i in j]
24
+ return Files(sorted(file_list, key=file_sorter))
@@ -0,0 +1,45 @@
1
+ """The Mkdocs Plugin."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from mkdocs.config import base, config_options as c
6
+
7
+
8
+ class PluginConfig(base.Config):
9
+ build_fn = c.Optional(c.Type(str))
10
+ """Path to the build script / callable.
11
+
12
+ Possible formats:
13
+
14
+ - `my.module:Class.build_fn` (must be a classmethod / staticmethod)
15
+ - `my.module:build_fn`
16
+ - `path/to/file.py:build_fn`
17
+
18
+ Can also be remote.
19
+ The targeted callable gets the project instance as an argument and optionally
20
+ keyword arguments from setting below.
21
+ """
22
+ kwargs = c.Optional(c.Type(dict))
23
+ """Keyword arguments passed to the build script / callable.
24
+
25
+ Build scripts may have keyword arguments. You can set them by using this setting.
26
+ """
27
+ repo_path = c.Type(str, default=".")
28
+ """Path to the repository to create a website for. (`http://....my_project.git`)"""
29
+ clone_depth = c.Type(int, default=100)
30
+ """Clone depth in case the repository is remote. (Required for `git-changelog`)."""
31
+ build_folder = c.Optional(c.Type(str))
32
+ """Folder to create the Markdown files in.
33
+
34
+ If no folder is set, **MkNodes** will generate a temporary dir."""
35
+ show_page_info = c.Type(bool, default=False)
36
+ """Append an admonition box with build-related information.
37
+
38
+ If True, all pages get added an expandable admonition box at the bottom,
39
+ containing information about the created page.
40
+ This includes:
41
+ - Metadata
42
+ - Resources
43
+ - Code which created the page (needs the page to be created via decorators, or
44
+ the `generated_by` attribute of the MkPage needs to be set manually)
45
+ """
@@ -0,0 +1,228 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Mapping
4
+ import contextlib
5
+ import io
6
+ import os
7
+ import pathlib
8
+ import shutil
9
+ import tempfile
10
+
11
+ from typing import TYPE_CHECKING, Any
12
+ from urllib.parse import urlsplit
13
+
14
+ import jinja2.exceptions
15
+
16
+
17
+ # from mkdocs.commands import serve as serve_
18
+ from mkdocs.config import load_config
19
+ from mkdocs.exceptions import Abort
20
+ from mkdocs.livereload import LiveReloadServer
21
+ from mknodes import paths
22
+ from mknodes.utils import log, yamlhelpers
23
+
24
+ from mkdocs_mknodes.plugin import build_page
25
+
26
+
27
+ if TYPE_CHECKING:
28
+ from mkdocs.config.defaults import MkDocsConfig
29
+
30
+ logger = log.get_logger(__name__)
31
+
32
+
33
+ def serve(
34
+ config: str | os.PathLike | MkDocsConfig | Mapping[str, Any] = paths.CFG_DEFAULT,
35
+ **kwargs,
36
+ ):
37
+ """Serve a MkNodes-based website."""
38
+ match config:
39
+ case str() | os.PathLike():
40
+ text = pathlib.Path(config).read_text(encoding="utf-8")
41
+ case _:
42
+ text = yamlhelpers.dump_yaml(dict(config))
43
+ stream = io.StringIO(text)
44
+ _serve(config_file=stream, livereload=False, **kwargs) # type: ignore[arg-type]
45
+
46
+
47
+ def serve_node(node, repo_path: str = "."):
48
+ text = f"""
49
+ import mknodes
50
+
51
+ def build(project):
52
+ root = project.get_root()
53
+ page = root.add_index_page(hide="toc")
54
+ page += '''{node!s}'''
55
+
56
+
57
+ """
58
+ p = pathlib.Path("docs/test.py")
59
+ p.write_text(text)
60
+ serve(repo_url=repo_path, site_script=p)
61
+
62
+
63
+ @contextlib.contextmanager
64
+ def catch_exceptions(config, site_dir):
65
+ try:
66
+ yield
67
+ except jinja2.exceptions.TemplateError:
68
+ # This is a subclass of OSError, but shouldn't be suppressed.
69
+ raise
70
+ except OSError as e: # pragma: no cover
71
+ # Avoid ugly, unhelpful traceback
72
+ msg = f"{type(e).__name__}: {e}"
73
+ raise Abort(msg) from e
74
+ finally:
75
+ config.plugins.on_shutdown()
76
+ if pathlib.Path(site_dir).is_dir():
77
+ shutil.rmtree(site_dir)
78
+
79
+
80
+ def _serve(
81
+ config_file: str | None = None,
82
+ livereload: bool = True,
83
+ build_type: str | None = None,
84
+ watch_theme: bool = False,
85
+ watch: list[str] | None = None,
86
+ **kwargs,
87
+ ) -> None:
88
+ """Start the MkDocs development server.
89
+
90
+ By default it will serve the documentation on http://localhost:8000/ and
91
+ it will rebuild the documentation and refresh the page automatically
92
+ whenever a file is edited.
93
+ """
94
+ watch = watch or []
95
+ site_dir = pathlib.Path(tempfile.mkdtemp(prefix="mkdocs_"))
96
+
97
+ def mount_path(config: MkDocsConfig):
98
+ return urlsplit(config.site_url or "/").path
99
+
100
+ def get_config():
101
+ config = load_config(config_file=config_file, site_dir=str(site_dir), **kwargs)
102
+ config.watch.extend(watch)
103
+ config.site_url = f"http://{config.dev_addr}{mount_path(config)}"
104
+ return config
105
+
106
+ is_clean = build_type == "clean"
107
+ is_dirty = build_type == "dirty"
108
+
109
+ config = get_config()
110
+ config.plugins.on_startup(command=("build" if is_clean else "serve"), dirty=is_dirty)
111
+
112
+ host, port = config.dev_addr
113
+ suffix = mount_path(config).lstrip("/").rstrip("/")
114
+ url = None if is_clean else f"http://{host}:{port}/{suffix}/"
115
+
116
+ def builder(config: MkDocsConfig | None = None):
117
+ logger.info("Building documentation...")
118
+ if config is None:
119
+ config = get_config()
120
+ build_page._build(config, live_server_url=url, dirty=is_dirty)
121
+
122
+ server = LiveReloadServer(
123
+ builder=builder,
124
+ host=host,
125
+ port=port,
126
+ root=str(site_dir),
127
+ mount_path=mount_path(config),
128
+ )
129
+
130
+ def error_handler(code) -> bytes | None:
131
+ if code not in (404, 500):
132
+ return None
133
+ error_page = site_dir / f"{code}.html"
134
+ if not error_page.is_file():
135
+ return None
136
+ with error_page.open("rb") as f:
137
+ return f.read()
138
+
139
+ server.error_handler = error_handler
140
+
141
+ try:
142
+ # Perform the initial build
143
+ builder(config)
144
+
145
+ if livereload:
146
+ # Watch the documentation files, the config file and the theme files.
147
+ server.watch(config.docs_dir)
148
+ if config.config_file_path:
149
+ server.watch(config.config_file_path)
150
+
151
+ if watch_theme:
152
+ for d in config.theme.dirs:
153
+ server.watch(d)
154
+
155
+ # Run `serve` plugin events.
156
+ server = config.plugins.on_serve(server, config=config, builder=builder)
157
+
158
+ for item in config.watch:
159
+ server.watch(item)
160
+
161
+ try:
162
+ server.serve()
163
+ except KeyboardInterrupt:
164
+ logger.info("Shutting down...")
165
+ finally:
166
+ server.shutdown()
167
+ except jinja2.exceptions.TemplateError:
168
+ # This is a subclass of OSError, but shouldn't be suppressed.
169
+ raise
170
+ except OSError as e: # pragma: no cover
171
+ # Avoid ugly, unhelpful traceback
172
+ msg = f"{type(e).__name__}: {e}"
173
+ raise Abort(msg) from None
174
+ finally:
175
+ config.plugins.on_shutdown()
176
+ if site_dir.is_dir():
177
+ shutil.rmtree(site_dir)
178
+
179
+ # # Perform the initial build
180
+ # with catch_exceptions(config, site_dir):
181
+ # builder(config)
182
+
183
+ # server = LiveReloadServer(
184
+ # builder=builder,
185
+ # host=host,
186
+ # port=port,
187
+ # root=site_dir,
188
+ # mount_path=mount_path(config),
189
+ # )
190
+
191
+ # def error_handler(code) -> bytes | None:
192
+ # if code not in (404, 500):
193
+ # return None
194
+ # error_page = pathlib.Path(site_dir) / f"{code}.html"
195
+ # if not error_page.is_file():
196
+ # return None
197
+ # with error_page.open("rb") as f:
198
+ # return f.read()
199
+
200
+ # # Run the server
201
+ # server.error_handler = error_handler
202
+ # with catch_exceptions(config, site_dir):
203
+ # run_server(server, config, builder, livereload, watch_theme)
204
+
205
+
206
+ # def run_server(server, config, builder, livereload, watch_theme):
207
+ # if livereload:
208
+ # # Watch the documentation files, the config file and the theme files.
209
+ # server.watch(config.docs_dir)
210
+ # if config.config_file_path:
211
+ # server.watch(config.config_file_path)
212
+
213
+ # if watch_theme:
214
+ # for d in config.theme.dirs:
215
+ # server.watch(d)
216
+
217
+ # # Run `serve` plugin events.
218
+ # server = config.plugins.on_serve(server, config=config, builder=builder)
219
+
220
+ # for item in config.watch:
221
+ # server.watch(item)
222
+
223
+ # try:
224
+ # server.serve()
225
+ # except KeyboardInterrupt:
226
+ # logger.info("Shutting down...")
227
+ # finally:
228
+ # server.shutdown()
@@ -0,0 +1,55 @@
1
+ Build process
2
+
3
+ - Clone repository (in case it is a remote one)
4
+ - Aggregate information about repository from:
5
+
6
+ - metadata.Distribution
7
+ - PyProject File
8
+ - MkDocs Config file
9
+ - Other config-related files
10
+ - Git info (aquired from GitPython)
11
+ - GitHub info (using PyGitHub)
12
+
13
+ - Build node tree based on Build script / function
14
+ - Populate mknodes-specific Jinja environment with all collected metadata
15
+ - Render jinja stuff with our own environment on node level
16
+ - Convert node tree to a file folder structure containing markdown files (using literate-nav-style SUMMARY.md files to describe the hierarchy)
17
+ - Gather information from the nodes about required Extensions / CSS / JavaScript
18
+ - Merge node requirements with provided MkDocs config file
19
+ - Let mkdocs-literate-nav populate the Navigation based on generated SUMMARY.mds
20
+ - Let MkDocs convert everything to HTML based on the composite config
21
+
22
+ ```mermaid
23
+ flowchart
24
+ style 437499 fill:#0000AA
25
+ style 553415 fill:#0000AA
26
+ style 618757 fill:#660000
27
+ style 683622 fill:#660000
28
+ style 332511 fill:#9f00df
29
+ style 893065 fill:#9f00df
30
+ 714252["MkNav"] --- 463152["MkPage"]
31
+ 553415[("Project X")] --- 714252
32
+ 618757[("Project Y")] --- 471096["Root MkNav"]
33
+ 471096 --- 714252
34
+ 332511[("Project Z")] --- 463152
35
+ subgraph 683622["Context Y"]
36
+ 310485["MkNav"] --- 831529["MkPage"]
37
+ 831529 --- 412394["MkNode"]
38
+ 831529 --- 591080["..."]
39
+ 167774["MkPage"] --- 512291["MkNode"]
40
+ 167774 --- 545444["..."]
41
+ 471096 --- 310485
42
+ 471096 --- 167774
43
+ end
44
+ subgraph 437499["Context X"]
45
+ 103229["MkPage"] --- 601764["MkNode"]
46
+ 103229 --- 769363["..."]
47
+ 714252 --- 103229
48
+ end
49
+ subgraph 893065["Context Z"]
50
+ 463152 --- 920059["MkNode"]
51
+ 463152 --- 503161["..."]
52
+ 920059 --- 645054["MkNode"]
53
+ 920059 --- 549467["..."]
54
+ end
55
+ ```
@@ -0,0 +1,15 @@
1
+ `MkNodes` offers a CLI interface in order to build projects based on
2
+ Callables. The CLI is closely aligned to the MkDocs CLI to simplify the usage. Most
3
+ arguments have the same name.
4
+
5
+
6
+ There are 3 diffent commands right now:
7
+
8
+ - `mknodes build`: Closely aligned to `mkdocs build`, but with the option to point
9
+ to a (remote) repository as well as a Website template in form of a Python Callable.
10
+
11
+ - `mknodes serve`: Same as `mknodes build`, but for serving the page.
12
+
13
+ - `mknodes create-config`: Does a test run with given callable and repository and
14
+ creates a Config file based on the metadata and extension requirements provided
15
+ by the combination of Callable and repository.