From 694f9cdf20e8563d738b16bfefdfbf3fd5c548ad Mon Sep 17 00:00:00 2001 From: Philipp Temminghoff Date: Tue, 19 Sep 2023 09:27:20 +0200 Subject: [PATCH] refactor: get rid of show_source kwarg for decorators --- mknodes/manual/cli_section.py | 6 ++-- mknodes/manual/dev_section.py | 18 +++++------ mknodes/manual/internals_section.py | 8 ++--- mknodes/manual/navs_section.py | 18 ++++------- mknodes/manual/nodes_section.py | 14 ++++----- mknodes/manual/routing.py | 6 ++-- mknodes/manual/use_cases_section.py | 4 +-- mknodes/navs/navrouter.py | 48 +++-------------------------- mknodes/plugin/__init__.py | 16 ++++++++++ 9 files changed, 55 insertions(+), 83 deletions(-) diff --git a/mknodes/manual/cli_section.py b/mknodes/manual/cli_section.py index 56669f45..a4a488ec 100644 --- a/mknodes/manual/cli_section.py +++ b/mknodes/manual/cli_section.py @@ -47,16 +47,16 @@ def create_cli_section(root_nav: mk.MkNav): page += mk.MkAdmonition(code, title=SECTION_CODE, collapsible=True, typ="quote") -@nav.route.page("build", show_source=True, icon="wrench") +@nav.route.page("build", icon="wrench") def create_build_page(page: mk.MkPage): page += mk.MkClickDoc("mknodes.cli:cli", prog_name="build") -@nav.route.page("serve", show_source=True, icon="web") +@nav.route.page("serve", icon="web") def create_changelog_page(page: mk.MkPage): page += mk.MkClickDoc("mknodes.cli:cli", prog_name="serve") -@nav.route.page("create-config", show_source=True, icon="folder-wrench") +@nav.route.page("create-config", icon="folder-wrench") def create_coc_page(page: mk.MkPage): page += mk.MkClickDoc("mknodes.cli:cli", prog_name="create-config") diff --git a/mknodes/manual/dev_section.py b/mknodes/manual/dev_section.py index 39d46e17..e1618492 100644 --- a/mknodes/manual/dev_section.py +++ b/mknodes/manual/dev_section.py @@ -26,47 +26,47 @@ def create_development_section(root_nav: mk.MkNav): page += mk.MkCode.for_object(create_development_section, header=SECTION_CODE) -@nav.route.page("Module overview", show_source=True, icon="file-tree-outline") +@nav.route.page("Module overview", icon="file-tree-outline") def create_module_overview_page(page: mk.MkPage): page += mk.MkModuleOverview(maximum_depth=2) -@nav.route.page("Plugin flow", show_source=True, icon="dev-to") +@nav.route.page("Plugin flow", icon="dev-to") def create_plugin_flow_page(page: mk.MkPage): page += mk.MkPluginFlow() -@nav.route.page("Changelog", show_source=True, icon="format-list-group") +@nav.route.page("Changelog", icon="format-list-group") def create_changelog_page(page: mk.MkPage): page += mk.MkChangelog() -@nav.route.page("Code of conduct", show_source=True, icon="octicons/code-of-conduct-24") +@nav.route.page("Code of conduct", icon="octicons/code-of-conduct-24") def create_coc_page(page: mk.MkPage): page += mk.MkCodeOfConduct() -@nav.route.page("Contributing", show_source=True, icon="help") +@nav.route.page("Contributing", icon="help") def create_contribute_page(page: mk.MkPage): page += mk.MkCommitConventions() page += mk.MkPullRequestGuidelines() -@nav.route.page("License", show_source=True, hide="toc", icon="license") +@nav.route.page("License", hide="toc", icon="license") def create_license_page(page: mk.MkPage): page += mk.MkLicense() -@nav.route.page("Dependencies", show_source=True, hide="toc", icon="database") +@nav.route.page("Dependencies", hide="toc", icon="database") def create_dependencies_page(page: mk.MkPage): page += mk.MkDependencyTable() -@nav.route.page("Development environment", show_source=True, icon="dev-to") +@nav.route.page("Development environment", icon="dev-to") def create_dev_environment_page(page: mk.MkPage): page += mk.MkDevEnvSetup() -@nav.route.page("Dev Tools", show_source=True, icon="wrench") +@nav.route.page("Dev Tools", icon="wrench") def create_dev_tools_page(page: mk.MkPage): page += mk.MkDevTools() diff --git a/mknodes/manual/internals_section.py b/mknodes/manual/internals_section.py index 4ba22fac..31716304 100644 --- a/mknodes/manual/internals_section.py +++ b/mknodes/manual/internals_section.py @@ -17,23 +17,23 @@ def create_internals_section(root_nav: mk.MkNav): page += mk.MkCode.for_object(create_internals_section, header=SECTION_CODE) -# @nav.route.page("Tree", show_source=True, hide="toc", icon="graph") +# @nav.route.page("Tree", hide="toc", icon="graph") # def create_tree_page(page: mk.MkPage): # page += mk.MkHeader("This is the tree we built up to now.", level=3) # tree = page.root.get_tree_repr(detailed=False, max_depth=3) # page += mk.MkCode(tree, language="") -@nav.route.page("Requirements", hide="toc", icon="puzzle-edit", show_source=True) +@nav.route.page("Requirements", hide="toc", icon="puzzle-edit") def create_requirements_page(page: mk.MkPage): page += mk.MkJinjaTemplate("requirements.md") -@nav.route.page("Build Log", show_source=True, hide="toc", icon="puzzle-edit") +@nav.route.page("Build Log", hide="toc", icon="puzzle-edit") def create_log_page(page: mk.MkPage): page += mk.MkText("log() | MkCode", is_jinja_expression=True) -@nav.route.nav("Complete code", show_source=True) +@nav.route.nav("Complete code") def create_complete_code_section(nav: mk.MkNav): nav.parse.module("mknodes/manual/", hide="toc") diff --git a/mknodes/manual/navs_section.py b/mknodes/manual/navs_section.py index 9058a647..a21d7ea5 100644 --- a/mknodes/manual/navs_section.py +++ b/mknodes/manual/navs_section.py @@ -91,7 +91,7 @@ def create_navs_section(root_nav: mk.MkNav): page += mk.MkCode(text, header="The resulting MkNav") -@nav.route.nav("From file", show_source=True) +@nav.route.nav("From file") def create_from_file_section(nav: mk.MkNav): """Load an existing SUMMARY.md and attach it to given MkNav.""" # We will now demonstate loading an existing Nav tree. @@ -122,7 +122,7 @@ def create_from_file_section(nav: mk.MkNav): page += file_content_node -@nav.route.nav("From folder", show_source=True) +@nav.route.nav("From folder") def create_from_folder_section(nav: mk.MkNav): """Create a MkNav based on a folder tree containing markup files.""" # We are using a part of the previous nav tree. It's a subfolder without a SUMMARY.md. @@ -135,13 +135,13 @@ def create_from_folder_section(nav: mk.MkNav): page += mk.MkDocStrings(mk.MkTreeView) -@pages_nav.route.page("MkClassPage", show_source=True) +@pages_nav.route.page("MkClassPage") def create_mkclasspage_page(page: mk.MkPage): class_page = mk.MkClassPage(mk.MkCode, inclusion_level=False) page += mk.MkReprRawRendered(class_page) -@pages_nav.route.page("MkModulePage", show_source=True) +@pages_nav.route.page("MkModulePage") def create_mkmodulepage_page(page: mk.MkPage): import mkdocs.config @@ -149,12 +149,7 @@ def create_mkmodulepage_page(page: mk.MkPage): page += mk.MkReprRawRendered(module_page) -@pages_nav.route.page( - "Adding to MkPages", - hide="toc, nav", - status="new", - show_source=True, -) +@pages_nav.route.page("Adding to MkPages", hide="toc, nav", status="new") def create_adding_to_mkpages_page(page: mk.MkPage): """Create the "Adding to MkPages" MkPage and attach it to given MkNav.""" page += mk.MkAdmonition("You can add other MkNodes to a page sequentially.") @@ -170,7 +165,6 @@ def create_adding_to_mkpages_page(page: mk.MkPage): search_boost=2.0, subtitle="Subtitle", description="Description", - show_source=True, ) def create_metadata_page(page: mk.MkPage): """Create the "Metadata" MkPage and attach it to given nav.""" @@ -192,7 +186,7 @@ def create_mkdefaultwebsite_section(nav: mk.MkNav): nav += website_nav -@nav.route.nav("MkDoc", show_source=True) +@nav.route.nav("MkDoc") def create_mkdoc_section(nav: mk.MkNav): """Create the "Metadata" sub-MkNav and attach it to given nav.""" nav = nav.add_nav("MkDoc") diff --git a/mknodes/manual/nodes_section.py b/mknodes/manual/nodes_section.py index f4d36bf7..05222d2f 100644 --- a/mknodes/manual/nodes_section.py +++ b/mknodes/manual/nodes_section.py @@ -87,7 +87,7 @@ def create_class_page(kls: type[mk.MkNode], page: mk.MkPage): page += admonition -@nav.route.nav("Base nodes", show_source=True) +@nav.route.nav("Base nodes") def create_basic_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all base node pages to given MkNav.""" klasses = [ @@ -111,7 +111,7 @@ def create_basic_nodes_section(nav: mk.MkNav): page += mk.MkAdmonition(code, title=NODE_PAGE_TEXT, collapsible=True, typ="quote") -@nav.route.nav("Container nodes", show_source=True) +@nav.route.nav("Container nodes") def create_container_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all template node pages to given MkNav.""" klasses = [ @@ -137,7 +137,7 @@ def create_container_nodes_section(nav: mk.MkNav): page += mk.MkAdmonition(code, title=NODE_PAGE_TEXT, collapsible=True, typ="quote") -@nav.route.nav("Presentation nodes", show_source=True) +@nav.route.nav("Presentation nodes") def create_presentation_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all template node pages to given MkNav.""" klasses = [ @@ -153,7 +153,7 @@ def create_presentation_nodes_section(nav: mk.MkNav): page += mk.MkAdmonition(code, title=NODE_PAGE_TEXT, collapsible=True, typ="quote") -@nav.route.nav("Documentation nodes", show_source=True) +@nav.route.nav("Documentation nodes") def create_documentation_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all template node pages to given MkNav.""" klasses = [ @@ -173,7 +173,7 @@ def create_documentation_nodes_section(nav: mk.MkNav): page += mk.MkAdmonition(code, title=NODE_PAGE_TEXT, collapsible=True, typ="quote") -@nav.route.nav("About-the-project nodes", show_source=True) +@nav.route.nav("About-the-project nodes") def create_about_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all template node pages to given MkNav.""" klasses = [ @@ -199,7 +199,7 @@ def create_about_nodes_section(nav: mk.MkNav): page += mk.MkAdmonition(code, title=NODE_PAGE_TEXT, collapsible=True, typ="quote") -@nav.route.nav("Special nodes", show_source=True) +@nav.route.nav("Special nodes") def create_special_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all template node pages to given MkNav.""" klasses = [mk.MkSnippet, mk.MkInclude, mk.MkIFrame, mk.MkCommandOutput, mk.MkCallable] @@ -209,7 +209,7 @@ def create_special_nodes_section(nav: mk.MkNav): page += mk.MkAdmonition(code, title=NODE_PAGE_TEXT, collapsible=True, typ="quote") -@nav.route.nav("Block nodes", show_source=True) +@nav.route.nav("Block nodes") def create_block_nodes_section(nav: mk.MkNav): """Add a sub-MkNav containing all template node pages to given MkNav.""" klasses = [ diff --git a/mknodes/manual/routing.py b/mknodes/manual/routing.py index 2b5ce060..6ad3b877 100644 --- a/mknodes/manual/routing.py +++ b/mknodes/manual/routing.py @@ -24,19 +24,19 @@ def create_routing_section(root_nav: mk.MkNav): page += mk.MkDocStrings(navrouter.NavRouter, header="MkNav.route Docstrings") -@nav.route.page("Routed page", show_source=True) +@nav.route.page("Routed page") def routed_page(page: mk.MkPage): """Builds a MkPage and attaches it to the router MkNav.""" page += mk.MkAdmonition("I'm a page added via decorators!") -@nav.route.page("Routed", "Deeply", "Nested", "Nested page", show_source=True) +@nav.route.page("Routed", "Deeply", "Nested", "Nested page") def routed_nested_page(page: mk.MkPage): """Builds a nested MkPage and attaches it to the router MkNav.""" page += mk.MkAdmonition("I'm a nested page added via decorators!") -@nav.route.nav("Routed", "Deeply", "Nested", "Nav", show_source=True) +@nav.route.nav("Routed", "Deeply", "Nested", "Nav") def routed_nav(nav: mk.MkNav): """Builds a nested MkNav and attaches it to the router MkNav.""" index_page = nav.add_index_page() diff --git a/mknodes/manual/use_cases_section.py b/mknodes/manual/use_cases_section.py index fe022c38..7da64e19 100644 --- a/mknodes/manual/use_cases_section.py +++ b/mknodes/manual/use_cases_section.py @@ -50,7 +50,7 @@ def create_use_cases_section(root_nav: mk.MkNav): page += mk.MkAdmonition(code, title=SECTION_CODE, collapsible=True) -@nav.route.page("Creating a sample website", show_source=True, hide="toc") +@nav.route.page("Creating a sample website", hide="toc") def create_default_website_section(page: mk.MkPage): """Create the "Creating a sample website" MkPage.""" page += mk.MkText("The following config...") @@ -64,7 +64,7 @@ def create_default_website_section(page: mk.MkPage): page += mk.MkLink(url, as_button=True, icon="material/web") -@nav.route.page("Creating a website via config", show_source=True, hide="toc") +@nav.route.page("Creating a website via config", hide="toc") def create_custom_website_by_config(page: mk.MkPage): """Create the "Creating a sample website via config" MkPage.""" page += mk.MkText("The following config...") diff --git a/mknodes/navs/navrouter.py b/mknodes/navs/navrouter.py index da2c1428..4a35a3db 100644 --- a/mknodes/navs/navrouter.py +++ b/mknodes/navs/navrouter.py @@ -3,7 +3,7 @@ from collections.abc import Callable from typing import TYPE_CHECKING, Any -from mknodes.basenodes import mkadmonition, mkcode, mklink +from mknodes.basenodes import mklink from mknodes.navs import mknav from mknodes.pages import mkpage from mknodes.utils import log @@ -29,7 +29,6 @@ def __init__(self, nav: mknav.MkNav): def __call__( self, *path: str, - show_source: bool = False, ) -> Callable[[Callable], Callable]: """Decorator method to use for routing. @@ -41,29 +40,15 @@ def __call__( Arguments: path: The section path for the returned `MkNav` / `MkPage` - show_source: If True, a section containing the code will be inserted - at the start of the page (or index page if node is a Nav) """ def decorator(fn: Callable[..., NavSubType], path=path) -> Callable: node = fn() node.parent = self._nav - if show_source and isinstance(node, mkpage.MkPage): + if isinstance(node, mkpage.MkPage): node.created_by = fn - code = mkcode.MkCode.for_object(fn, header="Code for this page") - code.parent = node - node.items.insert(0, code) - elif show_source and isinstance(node, mknav.MkNav) and node.index_page: + elif isinstance(node, mknav.MkNav) and node.index_page: node.index_page.created_by = fn - code = mkcode.MkCode.for_object(fn) - details = mkadmonition.MkAdmonition( - code, - title="Code for this section", - collapsible=True, - typ="quote", - ) - details.parent = node.index_page - node.index_page.items.append(details) self._nav.nav[path] = node return fn @@ -72,7 +57,6 @@ def decorator(fn: Callable[..., NavSubType], path=path) -> Callable: def nav( self, *path: str, - show_source: bool = False, **kwargs: Any, ) -> Callable[[Callable], Callable]: """Decorator method to use for routing Navs. @@ -91,8 +75,6 @@ def _(nav: mk.MkNav): Arguments: path: The section path for the returned MkNav - show_source: If True, a section containing the code will be inserted - at the end of the index page of the MkNav) kwargs: Keyword arguments passed to the MkNav constructor. """ @@ -104,16 +86,8 @@ def decorator( node = mknav.MkNav(path[-1], parent=self._nav, **kwargs) node = fn(node) or node node.parent = self._nav # in case a new MkPage was generated - if show_source and node.index_page: + if node.index_page: node.index_page.created_by = fn - code = mkcode.MkCode.for_object(fn) - details = mkadmonition.MkAdmonition( - code, - title="Code for this section", - collapsible=True, - typ="quote", - ) - node.index_page.append(details) self._nav.nav[path] = node return fn @@ -122,7 +96,6 @@ def decorator( def page( self, *path: str, - show_source: bool = False, **kwargs: Any, ) -> Callable[[Callable], Callable]: """Decorator method to use for routing Pages. @@ -141,8 +114,6 @@ def _(page: mk.MkPage): Arguments: path: The section path for the returned MkPage - show_source: If True, a section containing the code will be inserted - at the end of the page kwargs: Keyword arguments passed to the MkPage constructor. """ @@ -154,16 +125,7 @@ def decorator( node = mkpage.MkPage(path[-1], parent=self._nav, **kwargs) node = fn(node) or node node.parent = self._nav # in case a new MkPage was generated - if show_source: - node.created_by = fn - code = mkcode.MkCode.for_object(fn) - details = mkadmonition.MkAdmonition( - code, - title="Code for this page", - collapsible=True, - typ="quote", - ) - node.append(details) + node.created_by = fn self._nav.nav[path] = node return fn diff --git a/mknodes/plugin/__init__.py b/mknodes/plugin/__init__.py index 62aadd5a..0d1447cb 100644 --- a/mknodes/plugin/__init__.py +++ b/mknodes/plugin/__init__.py @@ -78,6 +78,8 @@ def on_files(self, files: Files, config: MkDocsConfig) -> Files: - Templates - CSS files """ + import mknodes as mk + if not self.config.build_fn: return files @@ -106,6 +108,20 @@ def on_files(self, files: Files, config: MkDocsConfig) -> Files: extra_files |= node.files match node: case mkpage.MkPage(): + if node.created_by: + code = mk.MkCode.for_object(node.created_by) + title = ( + "Code for this section" + if node.is_index() + else "Code for this page" + ) + details = mk.MkAdmonition( + code, + title=title, + collapsible=True, + typ="quote", + ) + node.append(details) if node.inclusion_level: path, md = node.resolved_file_path, node.to_markdown() node_files[path] = md