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.
- mkdocs_mknodes/__init__.py +1 -0
- mkdocs_mknodes/buildcollector.py +167 -0
- mkdocs_mknodes/cli/__init__.py +194 -0
- mkdocs_mknodes/manual/__init__.py +13 -0
- mkdocs_mknodes/manual/cli_section.py +37 -0
- mkdocs_mknodes/manual/dev_section.py +70 -0
- mkdocs_mknodes/manual/github_index.py +17 -0
- mkdocs_mknodes/manual/internals_section.py +74 -0
- mkdocs_mknodes/manual/multi_project.py +19 -0
- mkdocs_mknodes/manual/root.py +77 -0
- mkdocs_mknodes/manual/use_cases_section.py +34 -0
- mkdocs_mknodes/mkdocsconfig.py +141 -0
- mkdocs_mknodes/paths.py +11 -0
- mkdocs_mknodes/plugin/__init__.py +179 -0
- mkdocs_mknodes/plugin/build_page.py +165 -0
- mkdocs_mknodes/plugin/buildbackend.py +45 -0
- mkdocs_mknodes/plugin/linkreplacer.py +49 -0
- mkdocs_mknodes/plugin/markdownbackend.py +37 -0
- mkdocs_mknodes/plugin/mkdocsbackend.py +184 -0
- mkdocs_mknodes/plugin/mkdocsbuilder.py +127 -0
- mkdocs_mknodes/plugin/mkdocshelpers.py +24 -0
- mkdocs_mknodes/plugin/pluginconfig.py +45 -0
- mkdocs_mknodes/plugin/serve.py +228 -0
- mkdocs_mknodes/resources/build_process.jinja +55 -0
- mkdocs_mknodes/resources/cli_index.jinja +15 -0
- mkdocs_mknodes/resources/material_css.jinja +88 -0
- mkdocs_mknodes/resources/material_css_extra.jinja +223 -0
- mkdocs_mknodes/resources/mkclasspage.jinja +11 -0
- mkdocs_mknodes/resources/mkdocs_css.jinja +7 -0
- mkdocs_mknodes/resources/modulepage.md +11 -0
- mkdocs_mknodes/resources/python_objects.inv +0 -0
- mkdocs_mknodes/resources/requirements.md +31 -0
- mkdocs_mknodes/resources/use_case_by_config.jinja +10 -0
- mkdocs_mknodes/resources/use_case_default_website.jinja +10 -0
- mkdocs_mknodes/resources/use_cases_index.jinja +46 -0
- mkdocs_mknodes-0.0.2.dist-info/METADATA +96 -0
- mkdocs_mknodes-0.0.2.dist-info/RECORD +40 -0
- mkdocs_mknodes-0.0.2.dist-info/WHEEL +4 -0
- mkdocs_mknodes-0.0.2.dist-info/entry_points.txt +5 -0
- 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.
|