Skip to content

containers

Admonition

Bases: MdObj

Source code in mkreports/md/containers.py 
17
18
19
20
21
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
93
@register_md("Admonition")
@dataclass
class Admonition(MdObj):
    """
    An admonition to be added to a page. Can also be collapsed. For more
    details see also the Materials-theme for mkdocs.

    Args:
        obj (Union[MdObj, Text]): object in the admonition. Markdown object, string
            or SpacedText.
        title (Optional[str]): title shown in the admonition. If missing, defaults
            to 'kind'.
        kind (Literal[ 'note', 'abstract', 'info', 'tip', 'success', 'question', 'warning', 'failure', 'danger', 'bug', 'example', 'quote', 'code']): The type of
            admonition to be shown. See also the Materials-theme for mkdocs for
            more details.
        collapse (bool): Should the admonition be collapsed?
        page_info (Optional[PageInfo]): Only needed when 'kind=="code"'.
    """

    obj: Union[Text, MdObj]
    title: Optional[str] = None
    kind: Literal[
        "note",
        "abstract",
        "info",
        "tip",
        "success",
        "question",
        "warning",
        "failure",
        "danger",
        "bug",
        "example",
        "quote",
        "code",
    ] = "note"
    collapse: bool = False
    page_info: Optional[PageInfo] = None

    def __post_init__(self):
        assert self.page_info is not None
        # if code-admonition, we need to load additional css
        if self.kind == "code":
            rel_css_path = store_asset_relpath(
                Path("code_admonition.css"), self.page_info
            )
            page_settings = dict(css=[rel_css_path])
        else:
            page_settings = {}
        cont_settings = Settings(
            mkdocs={
                "markdown_extensions": [
                    "admonition",
                    "pymdownx.details",
                    "pymdownx.superfences",
                ]
            },
            page=page_settings,
        )
        if isinstance(self.obj, MdObj):
            admon_text = self.obj.body
            back = self.obj.back
            settings = self.obj.settings
            settings = cont_settings + settings
        else:
            admon_text, back, settings = str(self.obj), SpacedText(), cont_settings

        if self.title is None:
            title_md = ""
        else:
            title_md = f'"{self.title}"'

        self._body = SpacedText(
            f"{'???' if self.collapse else '!!!'} {self.kind} {title_md}", (2, 2)
        ) + SpacedText(indent(str(admon_text), "    "), (2, 2))
        self._back = back
        self._settings = settings

Code

Bases: MdObj

Source code in mkreports/md/containers.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
@register_md("Code")
@dataclass
class Code(MdObj):
    """
    Shows a code-block.

    Args:
        code (str): The code to be shown as a string.
        title (Optional[str]): Optional title for the code block.
        first_line (Optional[int]): Number at the first line.
        hl_lines (Optional[Tuple[int, int]]): Line-range for highlighting.
            Is counted relative to 'first_line'.
        language (Optional[str]): Language for syntax highlighting.
        dedent (bool): Should the string be de-dented?

    """

    code: str
    title: Optional[str] = None
    first_line: Optional[int] = None
    hl_lines: Optional[Tuple[int, int]] = None
    language: Optional[str] = "python"
    dedent: bool = True

    def __post_init__(self):
        annots = ""
        if self.language is not None:
            annots = annots + self.language
        if self.title is not None:
            annots = annots + f' title="{html.escape(self.title)}"'
        if self.first_line is not None:
            # hi_lines get intrepreted relative to first_line
            if self.hl_lines is not None:
                hl_lines = (
                    self.hl_lines[0] - self.first_line + 1,
                    self.hl_lines[1] - self.first_line + 1,
                )
            else:
                hl_lines = self.hl_lines
            annots = annots + f' linenums="{self.first_line}"'
        else:
            hl_lines = self.hl_lines

        if hl_lines is not None:
            annots = annots + f' hl_lines="{hl_lines[0]}-{hl_lines[1]}"'

        settings = Settings(
            mkdocs=dict(
                markdown_extensions=[{"pymdownx.highlight": dict(use_pygments=True)}]
            )
        )
        self._body = SpacedText(
            TextUtils.insert_code(textwrap.dedent(self.code), annots), (2, 2)
        )
        self._back = None
        self._settings = settings

CodeFile

Bases: File

Code block with the content of a file.

Source code in mkreports/md/containers.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
@register_md("CodeFile")
class CodeFile(File):
    """
    Code block with the content of a file.
    """

    def __init__(
        self,
        path: Union[Path, str],
        page_info: PageInfo,
        title: Optional[str] = None,
        hl_lines: Optional[Tuple[int, int]] = None,
        language: Optional[str] = "python",
    ):
        """
        Set up the code-block with file content.

        Args:
            path (Union[Path, str]): Abolute path or relative to current working dir for the
                code-file to be included.
            page_info (PageInfo): PageInfo on the page where the code is to be added.
            title (Optional[str]): Title of the code-block. If 'None', the path of the
                code file relative to the project root will be added. If it should be
                empty, set to empty string.
            hl_lines (Optional[Tuple[int, int]]): Optional range of lines for highlighting.
            language (Optional[str]): Language for syntax highlighting.
        """
        assert page_info.project_root is not None
        assert page_info.report_path is not None

        path = Path(path)

        super().__init__(path=path, page_info=page_info, allow_copy=True, use_hash=True)
        self.title = (
            title
            if title is not None
            else str(path.relative_to(page_info.project_root))
        )
        self.hl_lines = hl_lines
        self.language = language

        annots = ""
        if self.language is not None:
            annots = annots + self.language
        if self.title is not None:
            annots = annots + f' title="{html.escape(self.title)}"'

        hl_lines = self.hl_lines
        if hl_lines is not None:
            annots = annots + f' hl_lines="{hl_lines[0]}-{hl_lines[1]}"'

        settings = Settings(
            mkdocs=dict(
                markdown_extensions=[
                    "pymdownx.snippets",
                    {"pymdownx.highlight": dict(use_pygments=True)},
                ]
            )
        )
        self._body = SpacedText(
            TextUtils.insert_code(
                f"--8<-- '{self.path.relative_to(page_info.report_path)}'", annots
            ),
            (2, 2),
        )
        self._back = None
        self._settings = settings

__init__(path, page_info, title=None, hl_lines=None, language='python')

Set up the code-block with file content.

Parameters:

Name Type Description Default
path Union[Path, str]

Abolute path or relative to current working dir for the code-file to be included.

 required
page_info PageInfo

PageInfo on the page where the code is to be added.

 required
title Optional[str]

Title of the code-block. If 'None', the path of the code file relative to the project root will be added. If it should be empty, set to empty string.

 None
hl_lines Optional[Tuple[int, int]]

Optional range of lines for highlighting.

 None
language Optional[str]

Language for syntax highlighting.

 'python'
Source code in mkreports/md/containers.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
def __init__(
    self,
    path: Union[Path, str],
    page_info: PageInfo,
    title: Optional[str] = None,
    hl_lines: Optional[Tuple[int, int]] = None,
    language: Optional[str] = "python",
):
    """
    Set up the code-block with file content.

    Args:
        path (Union[Path, str]): Abolute path or relative to current working dir for the
            code-file to be included.
        page_info (PageInfo): PageInfo on the page where the code is to be added.
        title (Optional[str]): Title of the code-block. If 'None', the path of the
            code file relative to the project root will be added. If it should be
            empty, set to empty string.
        hl_lines (Optional[Tuple[int, int]]): Optional range of lines for highlighting.
        language (Optional[str]): Language for syntax highlighting.
    """
    assert page_info.project_root is not None
    assert page_info.report_path is not None

    path = Path(path)

    super().__init__(path=path, page_info=page_info, allow_copy=True, use_hash=True)
    self.title = (
        title
        if title is not None
        else str(path.relative_to(page_info.project_root))
    )
    self.hl_lines = hl_lines
    self.language = language

    annots = ""
    if self.language is not None:
        annots = annots + self.language
    if self.title is not None:
        annots = annots + f' title="{html.escape(self.title)}"'

    hl_lines = self.hl_lines
    if hl_lines is not None:
        annots = annots + f' hl_lines="{hl_lines[0]}-{hl_lines[1]}"'

    settings = Settings(
        mkdocs=dict(
            markdown_extensions=[
                "pymdownx.snippets",
                {"pymdownx.highlight": dict(use_pygments=True)},
            ]
        )
    )
    self._body = SpacedText(
        TextUtils.insert_code(
            f"--8<-- '{self.path.relative_to(page_info.report_path)}'", annots
        ),
        (2, 2),
    )
    self._back = None
    self._settings = settings

Tab

Bases: MdObj

Source code in mkreports/md/containers.py 
 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
129
130
131
132
133
134
135
136
137
@register_md("Tab")
@dataclass
class Tab(MdObj):
    """
    Tab interface

    Args:
        obj (Union[Text, MdObj]): The object to be shown in the tab. An MdObj,
            string or SpacedText.
        title (Optional[str]): Optional title for the tab.
    """

    obj: Union[Text, MdObj]
    title: Optional[str] = None

    def __post_init__(self):
        tab_settings = Settings(
            mkdocs={
                "markdown_extensions": [
                    "pymdownx.superfences",
                    {"pymdownx.tabbed": {"alternate_style": True}},
                ]
            }
        )
        if isinstance(self.obj, MdObj):
            tab_text = self.obj.body
            back = self.obj.back
            settings = self.obj.settings
            settings = tab_settings + settings
        else:
            tab_text, back, settings = str(self.obj), SpacedText(), tab_settings

        if self.title is not None:
            title_text = html.escape(self.title)
        else:
            title_text = ""

        self._body = SpacedText(f'=== "{title_text}"', (2, 2)) + SpacedText(
            indent(str(tab_text), "    "), (2, 2)
        )
        self._back = back
        self._settings = settings