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 @@
|
|
|
1
|
+
__version__ = "0.0.2"
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import collections
|
|
4
|
+
import itertools
|
|
5
|
+
import pathlib
|
|
6
|
+
|
|
7
|
+
from typing import TYPE_CHECKING
|
|
8
|
+
|
|
9
|
+
import mknodes as mk
|
|
10
|
+
|
|
11
|
+
from mknodes.info import contexts
|
|
12
|
+
from mknodes.utils import log, resources
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
if TYPE_CHECKING:
|
|
16
|
+
from mknodes.theme import theme as theme_
|
|
17
|
+
|
|
18
|
+
from mkdocs_mknodes.plugin import buildbackend
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
logger = log.get_logger(__name__)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def add_page_info(page: mk.MkPage, req: resources.Resources):
|
|
25
|
+
adm = mk.MkAdmonition([], title="Page info", typ="theme", collapsible=True)
|
|
26
|
+
|
|
27
|
+
if page.created_by:
|
|
28
|
+
typ = "section" if page.is_index() else "page"
|
|
29
|
+
code = mk.MkCode.for_object(page.created_by)
|
|
30
|
+
title = f"Code for this {typ}"
|
|
31
|
+
details = mk.MkAdmonition(code, title=title, collapsible=True, typ="quote")
|
|
32
|
+
adm += details
|
|
33
|
+
|
|
34
|
+
title = "Resources"
|
|
35
|
+
pretty = mk.MkPrettyPrint(req)
|
|
36
|
+
details = mk.MkAdmonition(pretty, title=title, collapsible=True, typ="quote")
|
|
37
|
+
adm += details
|
|
38
|
+
|
|
39
|
+
title = "Metadata"
|
|
40
|
+
code = mk.MkCode(str(page.metadata), language="yaml")
|
|
41
|
+
details = mk.MkAdmonition(code, title=title, collapsible=True, typ="quote")
|
|
42
|
+
adm += details
|
|
43
|
+
|
|
44
|
+
page += adm
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def update_page_template(page: mk.MkPage):
|
|
48
|
+
if page.template:
|
|
49
|
+
node_path = pathlib.Path(page.resolved_file_path)
|
|
50
|
+
elif any(i.page_template for i in page.parent_navs):
|
|
51
|
+
nav = next(i for i in page.parent_navs if i.page_template)
|
|
52
|
+
node_path = pathlib.Path(nav.resolved_file_path)
|
|
53
|
+
else:
|
|
54
|
+
node_path = None
|
|
55
|
+
if node_path:
|
|
56
|
+
html_path = node_path.with_suffix(".html").as_posix()
|
|
57
|
+
page._metadata.template = html_path
|
|
58
|
+
page.template.filename = html_path
|
|
59
|
+
if extends := _get_extends_from_parent(page):
|
|
60
|
+
page.template.extends = extends
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def update_nav_template(nav: mk.MkNav):
|
|
64
|
+
if nav.page_template:
|
|
65
|
+
path = pathlib.Path(nav.resolved_file_path)
|
|
66
|
+
html_path = path.with_suffix(".html").as_posix()
|
|
67
|
+
nav.metadata.template = html_path
|
|
68
|
+
nav.page_template.filename = html_path
|
|
69
|
+
if extends := _get_extends_from_parent(nav):
|
|
70
|
+
nav.page_template.extends = extends
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _get_extends_from_parent(node: mk.MkPage | mk.MkNav):
|
|
74
|
+
for nav in node.parent_navs:
|
|
75
|
+
if nav.page_template:
|
|
76
|
+
p = pathlib.Path(nav.resolved_file_path)
|
|
77
|
+
return p.with_suffix(".html").as_posix()
|
|
78
|
+
return None
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class BuildCollector:
|
|
82
|
+
"""A class to assist in extracting build stuff from a Node tree + Theme."""
|
|
83
|
+
|
|
84
|
+
def __init__(
|
|
85
|
+
self,
|
|
86
|
+
backends: list[buildbackend.BuildBackend],
|
|
87
|
+
show_page_info: bool = False,
|
|
88
|
+
):
|
|
89
|
+
"""Constructor.
|
|
90
|
+
|
|
91
|
+
Arguments:
|
|
92
|
+
backends: A list of backends which should be used for building
|
|
93
|
+
show_page_info: Add a admonition box containing page build info to each page
|
|
94
|
+
"""
|
|
95
|
+
self.backends = backends
|
|
96
|
+
self.show_page_info = show_page_info
|
|
97
|
+
self.node_files: dict[str, str | bytes] = {}
|
|
98
|
+
self.extra_files: dict[str, str | bytes] = {}
|
|
99
|
+
self.node_counter: collections.Counter[str] = collections.Counter()
|
|
100
|
+
self.resources = resources.Resources()
|
|
101
|
+
self.mapping: dict[str, mk.MkNode] = dict()
|
|
102
|
+
|
|
103
|
+
def collect(self, root: mk.MkNode, theme: theme_.Theme):
|
|
104
|
+
"""Collect build stuff from given node + theme.
|
|
105
|
+
|
|
106
|
+
Arguments:
|
|
107
|
+
root: A node to collect build stuff from
|
|
108
|
+
theme: A theme to collect build stuff from.
|
|
109
|
+
"""
|
|
110
|
+
logger.debug("Collecting theme resources...")
|
|
111
|
+
iterator = itertools.chain(theme.iter_nodes(), root.iter_nodes())
|
|
112
|
+
for _, node in iterator:
|
|
113
|
+
self.node_counter.update([node.__class__.__name__])
|
|
114
|
+
self.extra_files |= node.files
|
|
115
|
+
match node:
|
|
116
|
+
case mk.MkPage() as page:
|
|
117
|
+
self.collect_page(page)
|
|
118
|
+
case mk.MkNav() as nav:
|
|
119
|
+
self.collect_nav(nav)
|
|
120
|
+
logger.debug("Setting default markdown extensions...")
|
|
121
|
+
reqs = theme.get_resources()
|
|
122
|
+
self.resources.merge(reqs)
|
|
123
|
+
logger.debug("Adapting collected extensions to theme...")
|
|
124
|
+
theme.adapt_extensions(self.resources.markdown_extensions)
|
|
125
|
+
build_files = self.node_files | self.extra_files
|
|
126
|
+
for backend in self.backends:
|
|
127
|
+
logger.info("%s: Collecting data..", type(backend).__name__)
|
|
128
|
+
backend.collect(build_files, self.resources)
|
|
129
|
+
return contexts.BuildContext(
|
|
130
|
+
page_mapping=self.mapping,
|
|
131
|
+
resources=self.resources,
|
|
132
|
+
node_counter=self.node_counter,
|
|
133
|
+
build_files=build_files,
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
def collect_page(self, page: mk.MkPage):
|
|
137
|
+
if page.metadata.inclusion_level is False:
|
|
138
|
+
return
|
|
139
|
+
path = page.resolved_file_path
|
|
140
|
+
self.mapping[path] = page
|
|
141
|
+
req = page.get_resources()
|
|
142
|
+
self.resources.merge(req)
|
|
143
|
+
update_page_template(page)
|
|
144
|
+
if self.show_page_info:
|
|
145
|
+
add_page_info(page, req)
|
|
146
|
+
md = page.to_markdown()
|
|
147
|
+
self.node_files[path] = md
|
|
148
|
+
|
|
149
|
+
def collect_nav(self, nav: mk.MkNav):
|
|
150
|
+
logger.info("Processing section %r...", nav.section)
|
|
151
|
+
path = nav.resolved_file_path
|
|
152
|
+
self.mapping[path] = nav
|
|
153
|
+
update_nav_template(nav)
|
|
154
|
+
md = nav.to_markdown()
|
|
155
|
+
self.node_files[path] = md
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
if __name__ == "__main__":
|
|
159
|
+
project = mk.Project.for_mknodes()
|
|
160
|
+
from mknodes.manual import root
|
|
161
|
+
|
|
162
|
+
log.basic()
|
|
163
|
+
root.build(project)
|
|
164
|
+
if project._root:
|
|
165
|
+
collector = BuildCollector([])
|
|
166
|
+
ctx = collector.collect(project._root, project.theme)
|
|
167
|
+
print(ctx)
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
import typer as t
|
|
5
|
+
|
|
6
|
+
from mknodes import paths
|
|
7
|
+
from mknodes.info import mkdocsconfigfile
|
|
8
|
+
from mkdocs_mknodes.plugin import build_page, serve as serve_
|
|
9
|
+
from mknodes.utils import log, richhelpers, yamlhelpers
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
logger = log.get_logger(__name__)
|
|
13
|
+
|
|
14
|
+
cli = t.Typer(
|
|
15
|
+
name="MkNodes",
|
|
16
|
+
help=(
|
|
17
|
+
" 🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀\n\n"
|
|
18
|
+
"Check out https://phil65.github.io/mknodes/ !"
|
|
19
|
+
),
|
|
20
|
+
no_args_is_help=True,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
REPO_HELP = "Repository URL of the target package. Can be remote or local."
|
|
24
|
+
BUILD_HELP = "Path to the build script. (form: `path.to.module:function` )"
|
|
25
|
+
SITE_DIR_HELP = "Path to the folder where the HTML should get written."
|
|
26
|
+
DEPTH_HELP = (
|
|
27
|
+
"Git clone depth in case repository is remote. Important for changelog generation."
|
|
28
|
+
)
|
|
29
|
+
CFG_PATH_HELP = "Path to the config file."
|
|
30
|
+
STRICT_HELP = "Strict mode (fails on warnings)"
|
|
31
|
+
THEME_HELP = "Theme to use for the build. Overrides config setting."
|
|
32
|
+
USE_DIR_URLS_HELP = "Use directory-style URLs."
|
|
33
|
+
VERBOSE_HELP = "Enable verbose output. (`DEBUG` level)"
|
|
34
|
+
QUIET_HELP = "Suppress output during build."
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
REPO_CMDS = "-r", "--repo-url"
|
|
38
|
+
SITE_DIR_CMDS = "-d", "--site-dir"
|
|
39
|
+
BUILD_CMS = "-b", "--build-fn"
|
|
40
|
+
DEPTH_CMDS = "-c", "--clone-depth"
|
|
41
|
+
CFG_PATH_CMDS = "-p", "--config-path"
|
|
42
|
+
STRICT_CMDS = "-s", "--strict"
|
|
43
|
+
THEME_CMDS = "-t", "--theme"
|
|
44
|
+
USE_DIR_URLS_CMDS = "-u", "--use-dir-urls"
|
|
45
|
+
VERBOSE_CMDS = "-v", "--verbose"
|
|
46
|
+
QUIET_CMDS = "-q", "--quiet"
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def verbose(ctx: t.Context, param: t.CallbackParam, value: bool):
|
|
50
|
+
# sourcery skip: move-assign
|
|
51
|
+
state = ctx.ensure_object(richhelpers.RichState)
|
|
52
|
+
if value:
|
|
53
|
+
state.stream.setLevel(logging.DEBUG)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def quiet(ctx: t.Context, param: t.CallbackParam, value: bool):
|
|
57
|
+
# sourcery skip: move-assign
|
|
58
|
+
state = ctx.ensure_object(richhelpers.RichState)
|
|
59
|
+
if value:
|
|
60
|
+
state.stream.setLevel(logging.ERROR)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@cli.command()
|
|
64
|
+
def build(
|
|
65
|
+
repo_path: str = t.Option(None, *REPO_CMDS, help=REPO_HELP, show_default=False),
|
|
66
|
+
build_fn: str = t.Option(None, *BUILD_CMS, help=BUILD_HELP, show_default=False),
|
|
67
|
+
site_dir: str = t.Option("site", *SITE_DIR_CMDS, help=SITE_DIR_HELP),
|
|
68
|
+
clone_depth: int = t.Option(None, *DEPTH_CMDS, help=DEPTH_HELP, show_default=False),
|
|
69
|
+
config_path: str = t.Option(paths.CFG_DEFAULT, *CFG_PATH_CMDS, help=CFG_PATH_HELP),
|
|
70
|
+
theme: str = t.Option("material", *THEME_CMDS, help=THEME_HELP),
|
|
71
|
+
strict: bool = t.Option(False, *STRICT_CMDS, help=STRICT_HELP),
|
|
72
|
+
use_directory_urls: bool = t.Option(True, *USE_DIR_URLS_CMDS, help=USE_DIR_URLS_HELP),
|
|
73
|
+
_verbose: bool = t.Option(False, *VERBOSE_CMDS, help=VERBOSE_HELP, callback=verbose),
|
|
74
|
+
_quiet: bool = t.Option(False, *QUIET_CMDS, help=QUIET_HELP, callback=quiet),
|
|
75
|
+
):
|
|
76
|
+
"""Create a MkNodes-based website, locally or remotely.
|
|
77
|
+
|
|
78
|
+
Runs the build script on given repository (either locally or a hosted one), adapts
|
|
79
|
+
the config file automatically and creates the HTML website in given site dir.
|
|
80
|
+
|
|
81
|
+
Further info here: https://phil65.github.io/mknodes/Development/CLI/
|
|
82
|
+
"""
|
|
83
|
+
cfg = mkdocsconfigfile.MkDocsConfigFile(config_path)
|
|
84
|
+
cfg.update_mknodes_section(
|
|
85
|
+
repo_url=repo_path,
|
|
86
|
+
build_fn=build_fn,
|
|
87
|
+
clone_depth=clone_depth,
|
|
88
|
+
)
|
|
89
|
+
cfg["site_dir"] = site_dir
|
|
90
|
+
build_page.build(
|
|
91
|
+
cfg,
|
|
92
|
+
strict=strict,
|
|
93
|
+
theme=theme if theme != "material" else None,
|
|
94
|
+
use_directory_urls=use_directory_urls,
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
@cli.command()
|
|
99
|
+
def serve(
|
|
100
|
+
repo_path: str = t.Option(None, *REPO_CMDS, help=REPO_HELP, show_default=False),
|
|
101
|
+
build_fn: str = t.Option(None, *BUILD_CMS, help=BUILD_HELP, show_default=False),
|
|
102
|
+
clone_depth: int = t.Option(None, *DEPTH_CMDS, help=DEPTH_HELP, show_default=False),
|
|
103
|
+
config_path: str = t.Option(paths.CFG_DEFAULT, *CFG_PATH_CMDS, help=CFG_PATH_HELP),
|
|
104
|
+
strict: bool = t.Option(False, *STRICT_CMDS, help=STRICT_HELP),
|
|
105
|
+
theme: str = t.Option("material", *THEME_CMDS, help=THEME_HELP),
|
|
106
|
+
use_directory_urls: bool = t.Option(True, *USE_DIR_URLS_CMDS, help=USE_DIR_URLS_HELP),
|
|
107
|
+
_verbose: bool = t.Option(False, *VERBOSE_CMDS, help=VERBOSE_HELP, callback=verbose),
|
|
108
|
+
_quiet: bool = t.Option(False, *QUIET_CMDS, help=QUIET_HELP, callback=quiet),
|
|
109
|
+
):
|
|
110
|
+
"""Serve a MkNodes-based website, locally or remotely.
|
|
111
|
+
|
|
112
|
+
Runs the build script on given repository (either locally or a hosted one), adapts
|
|
113
|
+
the config file automatically and serves a webpage on http://127.0.0.1/8000/.
|
|
114
|
+
|
|
115
|
+
Further info here: https://phil65.github.io/mknodes/Development/CLI/
|
|
116
|
+
"""
|
|
117
|
+
cfg = mkdocsconfigfile.MkDocsConfigFile(config_path)
|
|
118
|
+
cfg.update_mknodes_section(
|
|
119
|
+
repo_url=repo_path,
|
|
120
|
+
build_fn=build_fn,
|
|
121
|
+
clone_depth=clone_depth,
|
|
122
|
+
)
|
|
123
|
+
serve_.serve(
|
|
124
|
+
cfg,
|
|
125
|
+
strict=strict,
|
|
126
|
+
theme=theme if theme != "material" else None,
|
|
127
|
+
use_directory_urls=use_directory_urls,
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
@cli.command()
|
|
132
|
+
def create_config(
|
|
133
|
+
repo_path: str = t.Option(None, *REPO_CMDS, help=REPO_HELP, show_default=False),
|
|
134
|
+
build_fn: str = t.Option(None, *BUILD_CMS, help=BUILD_HELP, show_default=False),
|
|
135
|
+
# config_path: str = t.Option(paths.CFG_DEFAULT, *CFG_PATH_CMDS, help=CFG_PATH_HELP),
|
|
136
|
+
theme: str = t.Option("material", *THEME_CMDS, help=THEME_HELP),
|
|
137
|
+
use_directory_urls: bool = t.Option(True, *USE_DIR_URLS_CMDS, help=USE_DIR_URLS_HELP),
|
|
138
|
+
_verbose: bool = t.Option(False, *VERBOSE_CMDS, help=VERBOSE_HELP, callback=verbose),
|
|
139
|
+
_quiet: bool = t.Option(False, *QUIET_CMDS, help=QUIET_HELP, callback=quiet),
|
|
140
|
+
):
|
|
141
|
+
"""Create a config based on a given build setup.
|
|
142
|
+
|
|
143
|
+
Runs the build script on given repository (either locally or a hosted one),
|
|
144
|
+
infers the required resources (CSS / JS / Md extensions) as well as metadata
|
|
145
|
+
and creates a MkDocs config file.
|
|
146
|
+
|
|
147
|
+
Further info here: https://phil65.github.io/mknodes/Development/CLI/
|
|
148
|
+
"""
|
|
149
|
+
build_fn = build_fn or paths.DEFAULT_BUILD_FN
|
|
150
|
+
mknodes_plugin = dict(
|
|
151
|
+
mknodes={"repo_path": repo_path, "path": build_fn},
|
|
152
|
+
)
|
|
153
|
+
theme_name = theme or "material"
|
|
154
|
+
config = {
|
|
155
|
+
"site_name": "Not set",
|
|
156
|
+
"theme": theme_name,
|
|
157
|
+
"use_directory_urls": use_directory_urls,
|
|
158
|
+
"extra": {},
|
|
159
|
+
"plugins": [
|
|
160
|
+
"search",
|
|
161
|
+
"mkdocstrings",
|
|
162
|
+
"literate-nav",
|
|
163
|
+
mknodes_plugin,
|
|
164
|
+
],
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
from mknodes import project
|
|
168
|
+
from mknodes.theme import theme as theme_
|
|
169
|
+
|
|
170
|
+
skin = theme_.Theme(theme_name)
|
|
171
|
+
proj = project.Project(
|
|
172
|
+
base_url="",
|
|
173
|
+
use_directory_urls=True,
|
|
174
|
+
theme=skin,
|
|
175
|
+
repo=repo_path,
|
|
176
|
+
build_fn=build_fn,
|
|
177
|
+
clone_depth=1,
|
|
178
|
+
)
|
|
179
|
+
info = proj.build()
|
|
180
|
+
resources = info.resources
|
|
181
|
+
info = proj.context.metadata
|
|
182
|
+
config["markdown_extensions"] = resources.markdown_extensions
|
|
183
|
+
if social := info.social_info:
|
|
184
|
+
config["extra"]["social"] = social # type: ignore[index]
|
|
185
|
+
config["repo_path"] = info.repository_url
|
|
186
|
+
config["site_description"] = info.summary
|
|
187
|
+
config["site_name"] = info.distribution_name
|
|
188
|
+
config["site_author"] = info.author_name
|
|
189
|
+
result = yamlhelpers.dump_yaml(config)
|
|
190
|
+
print(result)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
if __name__ == "__main__":
|
|
194
|
+
cli(["build", "--help"])
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""Module containing the documentation."""
|
|
2
|
+
|
|
3
|
+
from .cli_section import create_cli_section
|
|
4
|
+
from .dev_section import create_development_section
|
|
5
|
+
from .use_cases_section import create_use_cases_section
|
|
6
|
+
from .root import build
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"create_cli_section",
|
|
10
|
+
"create_development_section",
|
|
11
|
+
"create_use_cases_section",
|
|
12
|
+
"build",
|
|
13
|
+
]
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import mknodes as mk
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
# this is the nav we will populate via decorators.
|
|
5
|
+
nav = mk.MkNav("CLI")
|
|
6
|
+
|
|
7
|
+
CLI_PATH = "mknodes.cli:cli"
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def create_cli_section(root_nav: mk.MkNav):
|
|
11
|
+
"""Create the "Development" sub-MkNav and attach it to given MkNav."""
|
|
12
|
+
# Now we will create the "Development" section.
|
|
13
|
+
# You might notice that this whole section does not contain any specific
|
|
14
|
+
# reference to mk. That is because all nodes containing metadata are
|
|
15
|
+
# dynamically populated depending on the project the tree is connected to.
|
|
16
|
+
# This means that this section could be imported by other packages and be
|
|
17
|
+
# used without any further adaptation.
|
|
18
|
+
root_nav += nav
|
|
19
|
+
page = nav.add_index_page(hide="toc")
|
|
20
|
+
page += mk.MkBinaryImage.for_file("docs/assets/cli.gif")
|
|
21
|
+
page += mk.MkJinjaTemplate("cli_index.jinja")
|
|
22
|
+
page.created_by = create_cli_section
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@nav.route.page("build", icon="wrench")
|
|
26
|
+
def _(page: mk.MkPage):
|
|
27
|
+
page += mk.MkClickDoc(CLI_PATH, prog_name="build")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@nav.route.page("serve", icon="web")
|
|
31
|
+
def _(page: mk.MkPage):
|
|
32
|
+
page += mk.MkClickDoc(CLI_PATH, prog_name="serve")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@nav.route.page("create-config", icon="folder-wrench")
|
|
36
|
+
def _(page: mk.MkPage):
|
|
37
|
+
page += mk.MkClickDoc(CLI_PATH, prog_name="create-config")
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import mknodes as mk
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
INTRO_TEXT = """MkNodes also contains some higher-order nodes to quickly put together
|
|
5
|
+
a Development section.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
# this is the nav we will populate via decorators.
|
|
9
|
+
nav = mk.MkNav("Development")
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def create_development_section(root_nav: mk.MkNav):
|
|
13
|
+
"""Create the "Development" sub-MkNav and attach it to given MkNav."""
|
|
14
|
+
# Now we will create the "Development" section.
|
|
15
|
+
# You might notice that this whole section does not contain any specific
|
|
16
|
+
# reference to mk. That is because all nodes containing metadata are
|
|
17
|
+
# dynamically populated depending on the project the tree is connected to.
|
|
18
|
+
# This means that this section could be imported by other packages and be
|
|
19
|
+
# used without any further adaptation.
|
|
20
|
+
root_nav += nav
|
|
21
|
+
page = nav.add_index_page(hide="toc")
|
|
22
|
+
page += INTRO_TEXT
|
|
23
|
+
page.created_by = create_development_section
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@nav.route.page("Module overview", icon="file-tree-outline")
|
|
27
|
+
def _(page: mk.MkPage):
|
|
28
|
+
page += mk.MkModuleOverview(maximum_depth=2)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@nav.route.page("Plugin flow", icon="dev-to")
|
|
32
|
+
def _(page: mk.MkPage):
|
|
33
|
+
page += mk.MkPluginFlow()
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@nav.route.page("Changelog", icon="format-list-group")
|
|
37
|
+
def _(page: mk.MkPage):
|
|
38
|
+
page += mk.MkChangelog()
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@nav.route.page("Code of conduct", icon="octicons/code-of-conduct-24")
|
|
42
|
+
def _(page: mk.MkPage):
|
|
43
|
+
page += mk.MkCodeOfConduct()
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@nav.route.page("Contributing", icon="help")
|
|
47
|
+
def _(page: mk.MkPage):
|
|
48
|
+
page += mk.MkCommitConventions()
|
|
49
|
+
page += mk.MkPullRequestGuidelines()
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
@nav.route.page("License", hide="toc", icon="license")
|
|
53
|
+
def _(page: mk.MkPage):
|
|
54
|
+
page += mk.MkLicense()
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@nav.route.page("Dependencies", hide="toc", icon="database")
|
|
58
|
+
def _(page: mk.MkPage):
|
|
59
|
+
page += mk.MkDependencyTable(layout="badge")
|
|
60
|
+
page += mk.MkPipDepTree(direction="LR")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@nav.route.page("Development environment", icon="dev-to")
|
|
64
|
+
def _(page: mk.MkPage):
|
|
65
|
+
page += mk.MkDevEnvSetup()
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@nav.route.page("Dev Tools", icon="wrench")
|
|
69
|
+
def _(page: mk.MkPage):
|
|
70
|
+
page += mk.MkDevTools()
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import mknodes
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
DOC_URL = "https://phil65.github.io/mknodes/"
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def create_github_index_md() -> mknodes.MkPage:
|
|
8
|
+
page = mknodes.MkPage("Github index")
|
|
9
|
+
page += mknodes.MkCode.for_object(create_github_index_md)
|
|
10
|
+
page += mknodes.MkHeader("MkNodes", level=1)
|
|
11
|
+
page += mknodes.MkHeader("Don't write docs. Code them.", level=4)
|
|
12
|
+
page += mknodes.MkShields()
|
|
13
|
+
page += mknodes.MkLink(DOC_URL, "Read the completely coded documentation!")
|
|
14
|
+
page += mknodes.MkInstallGuide(header="How to install")
|
|
15
|
+
page += mknodes.MkHeader("All the nodes!")
|
|
16
|
+
page += mknodes.MkClassDiagram(mknodes.MkNode, mode="subclasses", direction="LR")
|
|
17
|
+
return page
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import mknodes as mk
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
nav = mk.MkNav("Internals")
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
STEP_1 = (
|
|
8
|
+
"### Set up the working directory\nClone the repository (in case it is a remote one)"
|
|
9
|
+
)
|
|
10
|
+
STEP_2 = "### Aggregate info\nAggregate information about the repository from:"
|
|
11
|
+
INFO_PROVIDERS = [
|
|
12
|
+
"metadata.Distribution",
|
|
13
|
+
"PyProject File",
|
|
14
|
+
"MkDocs Config file",
|
|
15
|
+
"Other config-related files",
|
|
16
|
+
"Git info (aquired from GitPython)",
|
|
17
|
+
"GitHub info (using PyGitHub)",
|
|
18
|
+
]
|
|
19
|
+
STEP_3 = "### Build the tree\nBuild the MkNode tree based on Build script / function"
|
|
20
|
+
STEP_4 = (
|
|
21
|
+
"### Populate the environment\n"
|
|
22
|
+
"Populate mknodes-specific Jinja environment with all collected metadata"
|
|
23
|
+
)
|
|
24
|
+
STEP_5 = "### Render Jinja\nRender jinja stuff with our own environment on node level"
|
|
25
|
+
STEP_6 = (
|
|
26
|
+
"### Serialize tree to markdown files\n"
|
|
27
|
+
"Convert node tree to a file folder structure containing markdown files "
|
|
28
|
+
"(using literate-nav-style SUMMARY.md files to describe the hierarchy)"
|
|
29
|
+
)
|
|
30
|
+
STEP_7 = (
|
|
31
|
+
"### Collect resources\n"
|
|
32
|
+
"Gather information from the nodes about required Extensions / CSS / JavaScript"
|
|
33
|
+
)
|
|
34
|
+
STEP_8 = (
|
|
35
|
+
"### Build project config\nMerge node requirements with provided MkDocs config file"
|
|
36
|
+
)
|
|
37
|
+
STEP_9 = (
|
|
38
|
+
"### Menu generation\nLet mkdocs-literate-nav populate the Navigation based on"
|
|
39
|
+
" generated SUMMARY.mds"
|
|
40
|
+
)
|
|
41
|
+
STEP_10 = (
|
|
42
|
+
"### Convert to HTML\nLet MkDocs convert everything to HTML based on the composite"
|
|
43
|
+
" config"
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def create_internals_section(root_nav: mk.MkNav):
|
|
48
|
+
"""Create the "Internals" Sub-MkNav and attach it to given MkNav."""
|
|
49
|
+
root_nav += nav
|
|
50
|
+
page = nav.add_index_page(hide="toc")
|
|
51
|
+
page += "TODO"
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@nav.route.page("Build steps")
|
|
55
|
+
def _(page: mk.MkPage):
|
|
56
|
+
node = mk.MkTimeline()
|
|
57
|
+
node.add_item(date="Step 1", content=STEP_1)
|
|
58
|
+
ls = mk.MkList(INFO_PROVIDERS)
|
|
59
|
+
node.add_item(date="Step 2", content=mk.MkContainer([STEP_2, ls]))
|
|
60
|
+
node.add_item(date="Step 3", content=STEP_3)
|
|
61
|
+
node.add_item(date="Step 4", content=STEP_4)
|
|
62
|
+
node.add_item(date="Step 5", content=STEP_5)
|
|
63
|
+
node.add_item(date="Step 6", content=STEP_6)
|
|
64
|
+
node.add_item(date="Step 7", content=STEP_7)
|
|
65
|
+
node.add_item(date="Step 8", content=STEP_8)
|
|
66
|
+
node.add_item(date="Step 9", content=STEP_9)
|
|
67
|
+
node.add_item(date="Step 10", content=STEP_10)
|
|
68
|
+
page += node
|
|
69
|
+
page.created_by = create_internals_section
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@nav.route.nav("Complete code")
|
|
73
|
+
def _(nav: mk.MkNav):
|
|
74
|
+
nav.parse.module("mknodes/manual/", hide="toc")
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import mknodes as mk
|
|
2
|
+
|
|
3
|
+
from mknodes.theme import materialtheme
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def build(project: mk.Project[materialtheme.MaterialTheme]):
|
|
7
|
+
nav = project.get_root()
|
|
8
|
+
index_page = nav.add_index_page(hide="toc")
|
|
9
|
+
index_page += "## Sub-Pages"
|
|
10
|
+
websites = dict(
|
|
11
|
+
ruff="https://github.com/astral-sh/ruff.git",
|
|
12
|
+
MkDocStrings="https://github.com/mkdocstrings/mkdocstrings.git",
|
|
13
|
+
MkDocs="https://github.com/mkdocs/mkdocs.git",
|
|
14
|
+
)
|
|
15
|
+
for k, v in websites.items():
|
|
16
|
+
subproject = mk.Project.for_path(v)
|
|
17
|
+
website_nav = mk.MkDefaultWebsite(section=k, project=subproject)
|
|
18
|
+
nav += website_nav
|
|
19
|
+
index_page += mk.MkLink(target=website_nav, title=k, icon="link")
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import mknodes as mk
|
|
2
|
+
|
|
3
|
+
from mknodes import manual
|
|
4
|
+
from mknodes.theme import materialtheme
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
HEADER = r"{{metadata.summary}}"
|
|
8
|
+
|
|
9
|
+
INFO = "This is the source code for building this website:"
|
|
10
|
+
|
|
11
|
+
FOOTER = """We are done! This code created the whole website.
|
|
12
|
+
We will now go through each section and explain how we created it.
|
|
13
|
+
This is done by prepending the code used to create each section / page to the beginning
|
|
14
|
+
of every page of this website. We will now start by creating a fancy start page before
|
|
15
|
+
explaining all the MkNodes!
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
DOCSTRING_INFO = """
|
|
19
|
+
You will encounter stuff like this quite often: Nodes displaying themselves,
|
|
20
|
+
and blurred borders between code, docs, markdown and rendered html.
|
|
21
|
+
It will be a quite inception-ish experience.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def build(project: mk.Project[materialtheme.MaterialTheme]) -> mk.MkNav:
|
|
26
|
+
# We will use annotations to explain things a bit.
|
|
27
|
+
annotations = mk.MkAnnotations() # Our first node! DocStrings: # (1)
|
|
28
|
+
annotations[1] = mk.MkDocStrings(mk.MkAnnotations)
|
|
29
|
+
|
|
30
|
+
# MkDocStrings is based on "mkdocstrings" and, well... it can display docstrings.
|
|
31
|
+
# Who would have guessed that? Here are the docstrings for MkDocStrings:
|
|
32
|
+
|
|
33
|
+
annotations[2] = mk.MkDocStrings(mk.MkDocStrings) # (2)
|
|
34
|
+
annotations[3] = mk.MkAdmonition(DOCSTRING_INFO) # (3)
|
|
35
|
+
|
|
36
|
+
# Let us start with building the page.
|
|
37
|
+
# this Nav is basically the root of everything. It corresponds to your root
|
|
38
|
+
# SUMMARY.md and is the root of the complete tree we are building during this tour.
|
|
39
|
+
root_nav = project.get_root()
|
|
40
|
+
project.theme.announcement_bar = mk.MkMetadataBadges("websites")
|
|
41
|
+
project.theme.error_page.content = mk.MkAdmonition("Page does not exist!")
|
|
42
|
+
project.theme.content_area_width = 1300
|
|
43
|
+
project.theme.tooltip_width = 800
|
|
44
|
+
project.linkprovider.add_inv_file("https://mkdocstrings.github.io/objects.inv")
|
|
45
|
+
annotations[4] = mk.MkDocStrings(mk.MkNav) # (4)
|
|
46
|
+
|
|
47
|
+
# now we will create the nav sections and its pages one by one.
|
|
48
|
+
# For demonstration purposes, this process is split up into several functions.
|
|
49
|
+
# Each function here adds another Menu item to the root nav (aka the tabs at the top).
|
|
50
|
+
# We will get there later.
|
|
51
|
+
manual.create_use_cases_section(root_nav)
|
|
52
|
+
manual.create_cli_section(root_nav)
|
|
53
|
+
manual.create_development_section(root_nav)
|
|
54
|
+
annotations[5] = str(root_nav) # This is the root nav after it was modified: (5)
|
|
55
|
+
|
|
56
|
+
# Lets begin with the start page (aka the root index.md).
|
|
57
|
+
# This is the page you are lookin at right now.)
|
|
58
|
+
page = root_nav.add_index_page(hide="toc,nav")
|
|
59
|
+
|
|
60
|
+
# A MkPage can contain MkNodes which represent Markdown text.
|
|
61
|
+
page += mk.MkHeader(HEADER, level=3)
|
|
62
|
+
admonition = mk.MkAdmonition(INFO, typ="info", title="Built with MkNodes")
|
|
63
|
+
page += admonition # This adds (6) to the page.
|
|
64
|
+
|
|
65
|
+
# Now we add the MkNode you are looking at right now.
|
|
66
|
+
# DocStrings for for_object: (7)
|
|
67
|
+
page += mk.MkCode.for_object(build)
|
|
68
|
+
page += annotations # here we add the (invisible) annotations block to the page.
|
|
69
|
+
|
|
70
|
+
# We can still add more annotations, things only get written at the very end:
|
|
71
|
+
annotations[6] = admonition
|
|
72
|
+
annotations[7] = mk.MkDocStrings(mk.MkCode.for_object)
|
|
73
|
+
admonition = mk.MkAdmonition(mk.MkCode(str(annotations)))
|
|
74
|
+
annotations[8] = admonition # annotations in raw text: (8)
|
|
75
|
+
|
|
76
|
+
page += mk.MkAdmonition(FOOTER, typ="success")
|
|
77
|
+
return root_nav
|