chore: template work

docs/classpage_custom.jinja

@@ -0,0 +1,17 @@
+{% extends "classpage.md" %}
+{% block content %}
+
+{% if cls | hasattr("REQUIRED_EXTENSIONS") %}
+#### Required Extensions:
+
+{% for i in cls.REQUIRED_EXTENSIONS %}
+
+{{ i | styled(code=True) }}
+
+{% endfor %}
+
+{% endif %}
+
+{{ super() }}
+
+{% endblock %}

mknodes/jinja/environment.py

@@ -36,6 +36,7 @@ def load_file(path: str | os.PathLike) -> str:
     "removeprefix": str.removeprefix,
     "issubclass": issubclass,
     "isinstance": isinstance,
+    "hasattr": hasattr,
 }
 
 

mknodes/manual/navs_section.py

@@ -202,38 +202,11 @@ def create_mkdoc_section(nav: mk.MkNav):
     page = mkdoc_nav.add_index_page(hide_toc=True, icon="api")
     page += mk.MkCode.for_object(create_mkdoc_section, header=SECTION_CODE)
     page += mk.MkAdmonition(DOC_TEXT, typ="tip")
-    create_mknodes_section(mkdoc_nav)
-
-    # We could also filter specific subclasses,
-    # or do other fancy stuff to generate a customized, automated documentation
-    # like changing the default class page ("MkClassPage") of our docs,
-    # (The default contains MkDocStrings, a table for base classes,  eventual subclasses
-    # and an inheritance graph.)
-
-    # There is also an extension available for this module which offers tools and
-    # new nodes based on PySide6 / PyQt6. We can add its documentation easily:
-    # from prettyqt import prettyqtmarkdown
-
-    # addon_docs = nav.add_doc(module=prettyqtmarkdown, flatten_nav=True)
-    # addon_docs.collect_classes(recursive=True)
-
-
-# class ExtensionInfoProcessor(processors.ContainerProcessor):
-#     ID = "extension_info"
-
-#     def append_block(self, node: mk.MkContainer):
-#         extensions = ", ".join(f"`{i}`" for i in self.item.REQUIRED_EXTENSIONS)
-#         node += mk.MkAdmonition(extensions, title="Required extensions")
-
-#     def check_if_apply(self, node: mk.MkContainer):
-#         # only add this section for MkNodes which have required extensions
-#         return issubclass(self.item, mk.MkNode) and self.item.REQUIRED_EXTENSIONS
-
-
-def create_mknodes_section(nav: mk.MkNav):
-    mknodes_docs = nav.add_doc(module=mk, filter_by___all__=True)
-
+    page.env.add_template("docs/classpage_custom.jinja")
+    mknodes_docs = mkdoc_nav.add_doc(
+        module=mk,
+        filter_by___all__=True,
+        class_page="docs/classpage_custom.jinja",
+    )
     # now we collect the stuff we want to document.
     mknodes_docs.collect_classes(recursive=True)
-
-    # We are done. Creating the files will be done when the tree is written in the end.

mknodes/navs/mkdoc.py

@@ -210,7 +210,7 @@ def add_class_page(
         if isinstance(self.ClassPage, str):
             page = mkclasspage.MkClassPage(
                 klass=klass,
-                template_name=self.ClassPage,
+                template=self.ClassPage,
                 module_path=tuple(parts),
                 parent=self,
                 **kwargs,

mknodes/pages/mkclasspage.py

@@ -26,7 +26,7 @@ def __init__(
         *,
         path: str | os.PathLike | None = None,
         module_path: tuple[str, ...] | str | None = None,
-        template_name: str | None = None,
+        template: str | os.PathLike | None = None,
         **kwargs: Any,
     ):
         """Constructor.
@@ -36,7 +36,7 @@ def __init__(
             module_path: If given, overrides module returned by class.__module__
                          This can be useful if you want to link to an aliased class
                          (for example a class imported to __init__.py)
-            template_name: Name of the template to load
+            template: Name of the template to load
             path: Filename/path for the class page. defaults to [classname].md
             kwargs: keyword arguments passed to base class
         """
@@ -47,10 +47,10 @@ def __init__(
             case _:
                 self.parts = classhelpers.to_module_parts(module_path)
         # if user chooses custom template, we make default the parent
-        tpl = template_name or DEFAULT_TPL
+        tpl = template or DEFAULT_TPL
         super().__init__(
             path=path or pathlib.Path(f"{klass.__name__}.md"),
-            template_name=tpl,
+            template=tpl,
             template_parent=DEFAULT_TPL if tpl != DEFAULT_TPL else None,
             **kwargs,
         )

mknodes/pages/mkmodulepage.py

@@ -23,7 +23,7 @@ def __init__(
         *,
         klasses: list[type] | set[type] | None = None,
         path: str | os.PathLike | None = None,
-        template_name: str | None = None,
+        template: str | os.PathLike | None = None,
         **kwargs: Any,
     ):
         """Constructor.
@@ -33,16 +33,16 @@ def __init__(
             klasses: klasses to use
             path: Filename/path for the Module page. defaults to [modulename].md
             kwargs: further keyword arguments passed to parent
-            template_name: Name of the template to load
+            template: Name of the template to load
         """
         self.parts = classhelpers.to_module_parts(module)
         self.module = classhelpers.to_module(module)
         self.klasses = klasses or list(
             classhelpers.iter_classes(module=self.parts, module_filter=self.parts[0]),
         )
-        tpl_name = template_name or DEFAULT_TPL
+        tpl_name = template or DEFAULT_TPL
         super().__init__(
-            template_name=tpl_name,
+            template=tpl_name,
             template_parent=DEFAULT_TPL if tpl_name != DEFAULT_TPL else None,
             path=path or f"{self.parts[-1]}.md",
             **kwargs,

mknodes/pages/mktemplatepage.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import abc
+import os
 
 from mknodes.pages import mkpage
 from mknodes.utils import log
@@ -15,12 +16,12 @@ class MkTemplatePage(mkpage.MkPage, metaclass=abc.ABCMeta):
     def __init__(
         self,
         *args,
-        template_name: str,
+        template: str | os.PathLike,
         template_parent: str | None = None,
         **kwargs,
     ):
         super().__init__(*args, **kwargs)
-        self.template_name = template_name
+        self.template_main = template
         self.template_parent = template_parent
 
     @property
@@ -29,7 +30,12 @@ def extra_variables(self):
 
     def to_markdown(self) -> str:
         with self._env.with_globals(**self.extra_variables):
+            if isinstance(self.template_main, os.PathLike):
+                return self.env.render_file(
+                    self.template_main,
+                    parent_template=self.template_parent,
+                )
             return self.env.render_template(
-                self.template_name,
+                self.template_main,
                 parent_template=self.template_parent,
             )

mknodes/plugin/__init__.py

@@ -144,8 +144,6 @@ def on_env(self, env: jinja2.Environment, config: MkDocsConfig, files: Files):
         env.globals["mknodes"] = node_env.globals
         env.filters |= node_env.filters
         logger.debug("Added macros / filters to MkDocs jinja2 environment.")
-        # mknodes_macros = jinjahelpers.get_mknodes_macros()
-        # env.globals["mknodes"].update(mknodes_macros)
 
     def on_pre_page(
         self,

mknodes/resources/classpage.md

@@ -1,3 +1,5 @@
+{% block content %}
+
 {% if cls.__subclasses__() %}
 ### Sub classes
 {{ cls.__subclasses__() | MkClassTable }}
@@ -13,3 +15,5 @@
 ### 🛈 DocStrings
 
 {{ cls | MkDocStrings }}
+
+{% endblock %}