Using decorators

Code for this section

"""MkNodes routing example.

MkNodes also supports setting up Navs via decorators.
"""

import mknodes as mk


NAV_TEXT = """You can also use decorators to attach MkNavs. These navs then can continue
to build the tree without using decorators (by adding sub-navs).
"""

nav = mk.MkNav("Using decorators")


@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")
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")
def routed_nav(nav: mk.MkNav):
    """Builds a nested MkNav and attaches it to the router MkNav."""
    index_page = nav.add_page(is_index=True)
    index_page += mk.MkAdmonition(NAV_TEXT)
    page = nav.add_page("Routed section page")
    page += mk.MkAdmonition("Routed section page content")

MkNav.route Docstrings

Class used for MkNav decorator routing.

__call__

__call__(*path: str) -> Callable[[Callable], Callable]

Decorator method to use for routing.

The decorated functions need to return either a MkPage or an MkNav. They will get registered to the router-MkNav then.

In comparison to page() and nav(), it is not required to know in advance what will be returned.

Parameters:

Name	Type	Description	Default
path	str	The section path for the returned MkNav / MkPage	()

__init__

__init__(nav: MkNav)

Constructor.

Parameters:

Name	Type	Description	Default
nav	MkNav	MkNav to use for routing	required

nav

nav(*path: str, **kwargs: Any) -> Callable[[Callable], Callable]

Decorator method to use for routing Navs.

The decorated functions will get passed an MkNav as an argument which can be modified then. They will get registered to the router-MkNav afterwards.

There is also the possibility to create a new MkNav and return it in the decorated method, that MkNav takes preference then over the modified one.

Examples:

@nav.route.nav("Routed nav")
def _(nav: mk.MkNav):
    nav += ...

Parameters:

Name	Type	Description	Default
path	str	The section path for the returned MkNav	()
kwargs	Any	Keyword arguments passed to the MkNav constructor.	{}

page

page(*path: str, **kwargs: Any) -> Callable[[Callable], Callable]

Decorator method to use for routing Pages.

The decorated functions will get passed an MkPage as an argument which can be modified then. The resulting page will get registered to the router-MkNav afterwards.

There is also the possibility to create a new MkPage and return it in the decorated method, that MkPage takes preference then over the modified one.

The keyword arguments can be used to pass metadata-related keyword arguments to the MkPage constructor.

Examples:

@nav.route.page("Routed page", icon=...)
def _(page: mk.MkPage):
    page += ...

Args: path: The section path for the returned MkPage kwargs: Keyword arguments passed to the MkPage constructor.

Page info

Code for this section

@nav.route.nav("Routing")
def _(nav: mk.MkNav):
    page = routing.nav.add_page(is_index=True, icon="material/call-split", hide="toc")
    page += mk.MkCode.for_file(routing.__file__, header="Code for this section")
    page += mk.MkDocStrings(navrouter.NavRouter, header="MkNav.route Docstrings")
    return routing.nav

Resources

Resources(css=[],
          markdown_extensions={'attr_list': {},
                               'md_in_html': {},
                               'pymdownx.emoji': {'emoji_generator': <function to_svg at 0x7fd7a6931800>,
                                                  'emoji_index': <function twemoji at 0x7fd7a69316c0>},
                               'pymdownx.highlight': {'anchor_linenums': True,
                                                      'line_spans': '__span',
                                                      'pygments_lang_class': True},
                               'pymdownx.magiclink': {'repo': 'mknodes',
                                                      'repo_url_shorthand': True,
                                                      'user': 'phil65'},
                               'pymdownx.superfences': {}},
          plugins=[Plugin('mkdocstrings')],
          js=[],
          assets=[],
          packages=[])

Metadata

created:
  source_filename: /home/runner/work/mknodes/mknodes/mknodes/manual/navs_section.py
  source_function: _
  source_line_no: 45
hide:
- toc
icon: material/call-split
template: SUMMARY.html
title: Using decorators