Skip to content

handler

Classes

KiaraHandler

Bases: BaseHandler

The kiara handler class.

domain: The cross-documentation domain/language for this handler.
enable_inventory: Whether this handler is interested in enabling the creation
    of the `objects.inv` Sphinx inventory file.
Source code in src/kiara/doc/mkdocstrings/handler.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class KiaraHandler(BaseHandler):
    """
    The kiara handler class.

    Attributes:
    ----------
        domain: The cross-documentation domain/language for this handler.
        enable_inventory: Whether this handler is interested in enabling the creation
            of the `objects.inv` Sphinx inventory file.
    """

    domain: str = "kiara"  # type: ignore
    enable_inventory: bool = True  # type: ignore

    def collect(
        self, identifier: str, config: typing.MutableMapping[str, typing.Any]
    ) -> CollectorItem:
        """
        Collect the documentation tree given an identifier and selection options.

        Arguments:
        ---------
            identifier: The dotted-path of a Python object available in the Python path.
            config: Selection options, used to alter the data collection done by `pytkdocs`.


        Raises:
        ------
            CollectionError: When there was a problem collecting the object documentation.


        Returns:
        -------
            The collected object-tree.
        """
        import builtins

        tokens = identifier.split(".")

        if tokens[0] != "kiara_info":
            return None

        item_type = tokens[1]
        item_id = ".".join(tokens[2:])
        if not item_id:
            raise CollectionError(f"Invalid id: {identifier}")

        ctx: KiaraContextInfo = builtins.plugin_package_context_info  # type: ignore
        try:
            item: ItemInfo = ctx.get_info(item_type=item_type, item_id=item_id)
        except Exception as e:
            log_exception(e)
            raise CollectionError(f"Invalid id: {identifier}")

        result = {"obj": item, "identifier": identifier}
        return result

    def get_anchors(self, data: CollectorItem) -> typing.Tuple[str, ...]:
        if data is None:
            return ()

        return (data["identifier"], data["kiara_id"], data["obj"].get_id())

    def render(
        self, data: CollectorItem, config: typing.Mapping[str, typing.Any]
    ) -> str:
        # final_config = ChainMap(config, self.default_config)

        obj = data["obj"]
        html: str = obj.create_html()
        return html

Attributes

domain: str = 'kiara' class-attribute instance-attribute
enable_inventory: bool = True class-attribute instance-attribute

Functions

collect(identifier: str, config: typing.MutableMapping[str, typing.Any]) -> CollectorItem

Collect the documentation tree given an identifier and selection options.

identifier: The dotted-path of a Python object available in the Python path.
config: Selection options, used to alter the data collection done by `pytkdocs`.

CollectionError: When there was a problem collecting the object documentation.

The collected object-tree.
Source code in src/kiara/doc/mkdocstrings/handler.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def collect(
    self, identifier: str, config: typing.MutableMapping[str, typing.Any]
) -> CollectorItem:
    """
    Collect the documentation tree given an identifier and selection options.

    Arguments:
    ---------
        identifier: The dotted-path of a Python object available in the Python path.
        config: Selection options, used to alter the data collection done by `pytkdocs`.


    Raises:
    ------
        CollectionError: When there was a problem collecting the object documentation.


    Returns:
    -------
        The collected object-tree.
    """
    import builtins

    tokens = identifier.split(".")

    if tokens[0] != "kiara_info":
        return None

    item_type = tokens[1]
    item_id = ".".join(tokens[2:])
    if not item_id:
        raise CollectionError(f"Invalid id: {identifier}")

    ctx: KiaraContextInfo = builtins.plugin_package_context_info  # type: ignore
    try:
        item: ItemInfo = ctx.get_info(item_type=item_type, item_id=item_id)
    except Exception as e:
        log_exception(e)
        raise CollectionError(f"Invalid id: {identifier}")

    result = {"obj": item, "identifier": identifier}
    return result
get_anchors(data: CollectorItem) -> typing.Tuple[str, ...]
Source code in src/kiara/doc/mkdocstrings/handler.py 
79
80
81
82
83
def get_anchors(self, data: CollectorItem) -> typing.Tuple[str, ...]:
    if data is None:
        return ()

    return (data["identifier"], data["kiara_id"], data["obj"].get_id())
render(data: CollectorItem, config: typing.Mapping[str, typing.Any]) -> str
Source code in src/kiara/doc/mkdocstrings/handler.py 
85
86
87
88
89
90
91
92
def render(
    self, data: CollectorItem, config: typing.Mapping[str, typing.Any]
) -> str:
    # final_config = ChainMap(config, self.default_config)

    obj = data["obj"]
    html: str = obj.create_html()
    return html

Functions

get_handler(theme: str, custom_templates: typing.Union[str, None], mdx: typing.List[str], mdx_config: typing.Dict, handler_config: typing.Dict, tool_config: typing.Dict) -> KiaraHandler

Simply return an instance of PythonHandler.

theme: The theme to use when rendering contents.
custom_templates: Directory containing custom templates.
**config: Configuration passed to the handler.

An instance of `PythonHandler`.
Source code in src/kiara/doc/mkdocstrings/handler.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def get_handler(
    theme: str,
    custom_templates: typing.Union[str, None],
    mdx: typing.List[str],
    mdx_config: typing.Dict,
    handler_config: typing.Dict,
    tool_config: typing.Dict,
) -> KiaraHandler:
    """
    Simply return an instance of `PythonHandler`.

    Arguments:
    ---------
        theme: The theme to use when rendering contents.
        custom_templates: Directory containing custom templates.
        **config: Configuration passed to the handler.


    Returns:
    -------
        An instance of `PythonHandler`.
    """
    if custom_templates is not None:
        raise Exception("Custom templates are not supported for the kiara renderer.")

    # custom_templates = os.path.join(
    #     KIARA_RESOURCES_FOLDER, "templates", "info_templates"
    # )

    return KiaraHandler(
        "kiara",
        theme=theme,
        custom_templates=custom_templates,
    )