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 @@
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