Skip to content

zig

Zig handler for mkdocstrings.

Classes:

Functions:

  • get_handler –

    Simply return an instance of ZigHandler.

ZigConfig dataclass

ZigConfig(options: dict[str, Any] = dict())

Bases: ZigInputConfig

Zig handler configuration.

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

Attributes:

options class-attribute instance-attribute

options: dict[str, Any] = field(default_factory=dict)

Global options in mkdocs.yml.

coerce classmethod

coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
203
204
205
206
@classmethod
def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
    """Coerce data."""
    return super().coerce(**data)

from_data classmethod

from_data(**data: Any) -> Self

Create an instance from a dictionary.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
188
189
190
191
@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    return cls(**cls.coerce(**data))

ZigHandler

ZigHandler(config: ZigConfig, base_dir: Path, **kwargs: Any)

Bases: BaseHandler

The Zig handler class.

Parameters:

  • config (ZigConfig) –

    The handler configuration.

  • base_dir (Path) –

    The base directory of the project.

  • **kwargs (Any, default: {} ) –

    Arguments passed to the parent constructor.

Methods:

  • collect –

    Collect data given an identifier and selection configuration.

  • do_convert_markdown –

    Render Markdown text; for use inside templates.

  • do_heading –

    Render an HTML heading and register it for the table of contents. For use inside templates.

  • get_aliases –

    Get aliases for a given identifier.

  • get_extended_templates_dirs –

    Load template extensions for the given handler, return their templates directories.

  • get_headings –

    Return and clear the headings gathered so far.

  • get_inventory_urls –

    Return the URLs (and configuration options) of the inventory files to download.

  • get_options –

    Get combined default, global and local options.

  • get_templates_dir –

    Return the path to the handler's templates directory.

  • load_inventory –

    Yield items and their URLs from an inventory file streamed from in_file.

  • render –

    Render a template using provided data and configuration options.

  • render_backlinks –

    Render backlinks.

  • teardown –

    Teardown the handler.

  • update_env –

    Update the Jinja environment with any custom settings/filters/options for this handler.

Attributes:

  • base_dir –

    The base directory of the project.

  • config –

    The handler configuration.

  • custom_templates –

    The path to custom templates.

  • domain (str) –

    The cross-documentation domain/language for this handler.

  • enable_inventory (bool) –

    Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

  • env –

    The Jinja environment.

  • extra_css (str) –

    Extra CSS.

  • fallback_config (dict[str, Any]) –

    Fallback configuration for resolving anchors with mkdocstrings versions before 1.0.

  • fallback_theme (str) –

    The theme to fallback to.

  • global_options –

    The global configuration options.

  • md (Markdown) –

    The Markdown instance.

  • mdx –

    The Markdown extensions to use.

  • mdx_config –

    The configuration for the Markdown extensions.

  • name (str) –

    The handler's name.

  • outer_layer (bool) –

    Whether we're in the outer Markdown conversion layer.

  • theme –

    The selected theme.

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def __init__(self, config: ZigConfig, base_dir: Path, **kwargs: Any) -> None:
    """Initialize the handler.

    Parameters:
        config: The handler configuration.
        base_dir: The base directory of the project.
        **kwargs: Arguments passed to the parent constructor.
    """
    super().__init__(**kwargs)

    self.config = config
    """The handler configuration."""
    self.base_dir = base_dir
    """The base directory of the project."""
    self.global_options = config.options
    """The global configuration options."""

    self._collected: dict[str, CollectorItem] = {}

base_dir instance-attribute

base_dir = base_dir

The base directory of the project.

config instance-attribute

config = config

The handler configuration.

custom_templates instance-attribute

custom_templates = custom_templates

The path to custom templates.

domain class-attribute

domain: str = 'zig'

The cross-documentation domain/language for this handler.

enable_inventory class-attribute

enable_inventory: bool = False

Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

env instance-attribute

env = Environment(autoescape=True, loader=FileSystemLoader(paths), auto_reload=False)

The Jinja environment.

extra_css class-attribute instance-attribute

extra_css: str = ''

Extra CSS.

fallback_config class-attribute

fallback_config: dict[str, Any] = {}

Fallback configuration for resolving anchors with mkdocstrings versions before 1.0.

fallback_theme class-attribute

fallback_theme: str = 'material'

The theme to fallback to.

global_options instance-attribute

global_options = config.options

The global configuration options.

md property

md: Markdown

The Markdown instance.

Raises:

  • RuntimeError –

    When the Markdown instance is not set yet.

mdx instance-attribute

mdx = mdx

The Markdown extensions to use.

mdx_config instance-attribute

mdx_config = mdx_config

The configuration for the Markdown extensions.

name class-attribute

name: str = 'zig'

The handler's name.

outer_layer property

outer_layer: bool

Whether we're in the outer Markdown conversion layer.

theme instance-attribute

theme = theme

The selected theme.

collect

collect(identifier: str, options: ZigOptions) -> CollectorItem

Collect data given an identifier and selection configuration.

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
83
84
85
86
87
88
89
90
91
92
93
def collect(self, identifier: str, options: ZigOptions) -> CollectorItem:  # noqa: ARG002
    """Collect data given an identifier and selection configuration."""
    path = Path(identifier)
    if path.is_dir():
        modules = []
        for p in sorted(path.rglob("*.zig")):
            modules.append(self._parse_module(p))
    else:
        modules = [self._parse_module(path)]

    return modules

do_convert_markdown

do_convert_markdown(text: str, heading_level: int, html_id: str = '', *, strip_paragraph: bool = False, autoref_hook: AutorefsHookInterface | None = None) -> Markup

Render Markdown text; for use inside templates.

Parameters:

  • text (str) –

    The text to convert.

  • heading_level (int) –

    The base heading level to start all Markdown headings from.

  • html_id (str, default: '' ) –

    The HTML id of the element that's considered the parent of this element.

  • strip_paragraph (bool, default: False ) –

    Whether to exclude the <p> tag from around the whole output.

Returns:

  • Markup –

    An HTML string.

Source code in mkdocstrings/_internal/handlers/base.py
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
def do_convert_markdown(
    self,
    text: str,
    heading_level: int,
    html_id: str = "",
    *,
    strip_paragraph: bool = False,
    autoref_hook: AutorefsHookInterface | None = None,
) -> Markup:
    """Render Markdown text; for use inside templates.

    Arguments:
        text: The text to convert.
        heading_level: The base heading level to start all Markdown headings from.
        html_id: The HTML id of the element that's considered the parent of this element.
        strip_paragraph: Whether to exclude the `<p>` tag from around the whole output.

    Returns:
        An HTML string.
    """
    global _markdown_conversion_layer  # noqa: PLW0603
    _markdown_conversion_layer += 1
    # Nested directives can replace self._md; finish and reset the converter that started this conversion.
    md = self.md
    treeprocessors = md.treeprocessors
    id_prefix = html_id and html_id + "--"
    treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level  # ty:ignore[unresolved-attribute]
    treeprocessors[IdPrependingTreeprocessor.name].id_prefix = id_prefix  # ty:ignore[unresolved-attribute]
    treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph  # ty:ignore[unresolved-attribute]
    if BacklinksTreeProcessor.name in treeprocessors:
        treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id  # ty:ignore[unresolved-attribute]
    if autoref_hook and AutorefsInlineProcessor.name in md.inlinePatterns:
        md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook  # ty:ignore[unresolved-attribute]

    try:
        with ExitStack() as stack:
            if id_prefix and "fenced_code_block" in md.preprocessors:
                fences = md.preprocessors["fenced_code_block"]
                if isinstance(fences, SuperFencesBlockPreprocessor):
                    # SuperFences caches Highlight settings, so prefix its active values before preprocessing.
                    fences.get_hl_settings()
                    stack.enter_context(_prepend_code_ids(fences, id_prefix))
            return Markup(md.convert(text))
    finally:
        treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0  # ty:ignore[unresolved-attribute]
        treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""  # ty:ignore[unresolved-attribute]
        treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False  # ty:ignore[unresolved-attribute]
        if BacklinksTreeProcessor.name in treeprocessors:
            treeprocessors[BacklinksTreeProcessor.name].initial_id = None  # ty:ignore[unresolved-attribute]
        if AutorefsInlineProcessor.name in md.inlinePatterns:
            md.inlinePatterns[AutorefsInlineProcessor.name].hook = None  # ty:ignore[unresolved-attribute]
        md.reset()
        _markdown_conversion_layer -= 1

do_heading

do_heading(content: Markup, heading_level: int, *, role: str | None = None, hidden: bool = False, toc_label: str | None = None, skip_inventory: bool = False, **attributes: str) -> Markup

Render an HTML heading and register it for the table of contents. For use inside templates.

Parameters:

  • content (Markup) –

    The HTML within the heading.

  • heading_level (int) –

    The level of heading (e.g. 3 -> h3).

  • role (str | None, default: None ) –

    An optional role for the object bound to this heading.

  • hidden (bool, default: False ) –

    If True, only register it for the table of contents, don't render anything.

  • toc_label (str | None, default: None ) –

    The title to use in the table of contents ('data-toc-label' attribute).

  • skip_inventory (bool, default: False ) –

    Flag element to not be registered in the inventory (by setting a data-skip-inventory attribute).

  • **attributes (str, default: {} ) –

    Any extra HTML attributes of the heading.

Returns:

  • Markup –

    An HTML string.

Source code in mkdocstrings/_internal/handlers/base.py
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
def do_heading(
    self,
    content: Markup,
    heading_level: int,
    *,
    role: str | None = None,
    hidden: bool = False,
    toc_label: str | None = None,
    skip_inventory: bool = False,
    **attributes: str,
) -> Markup:
    """Render an HTML heading and register it for the table of contents. For use inside templates.

    Arguments:
        content: The HTML within the heading.
        heading_level: The level of heading (e.g. 3 -> `h3`).
        role: An optional role for the object bound to this heading.
        hidden: If True, only register it for the table of contents, don't render anything.
        toc_label: The title to use in the table of contents ('data-toc-label' attribute).
        skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).
        **attributes: Any extra HTML attributes of the heading.

    Returns:
        An HTML string.
    """
    # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
    # - register it in the ToC: right now we're in the inner Markdown conversion layer,
    #   so we have to bubble up the information to the outer Markdown conversion layer,
    #   for the ToC extension to pick it up.
    # - register it in autorefs: right now we don't know what page is being rendered,
    #   so we bubble up the information again to where autorefs knows the page,
    #   and can correctly register the heading anchor (id) to its full URL.
    # - register it in the objects inventory: same as for autorefs,
    #   we don't know the page here, or the handler (and its domain),
    #   so we bubble up the information to where the mkdocstrings extension knows that.
    el = Element(f"h{heading_level}", attributes)
    if toc_label is None:
        toc_label = content.unescape() if isinstance(content, Markup) else content
    el.set("data-toc-label", toc_label)
    if skip_inventory:
        el.set("data-skip-inventory", "true")
    if role:
        el.set("data-role", role)
    if content:
        el.text = str(content).strip()
    self._headings.append(el)

    if hidden:
        return Markup('<a id="{0}"></a>').format(attributes["id"])

    # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
    # Start with a heading that has just attributes (no text), and add a placeholder into it.
    el = Element(f"h{heading_level}", attributes)
    el.append(Element("mkdocstrings-placeholder"))
    # Tell the inner 'toc' extension to make its additions if configured so.
    toc = cast("TocTreeprocessor", self.md.treeprocessors["toc"])
    if toc.use_anchors:
        toc.add_anchor(el, attributes["id"])
    if toc.use_permalinks:
        toc.add_permalink(el, attributes["id"])

    # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
    # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
    # Now this HTML wrapper can be "filled" by replacing the placeholder.
    html_with_placeholder = tostring(el, encoding="unicode")
    assert (  # noqa: S101
        html_with_placeholder.count("<mkdocstrings-placeholder />") == 1
    ), f"Bug in mkdocstrings: failed to replace in {html_with_placeholder!r}"
    html = html_with_placeholder.replace("<mkdocstrings-placeholder />", content)
    return Markup(html)

get_aliases

get_aliases(identifier: str) -> tuple[str, ...]

Get aliases for a given identifier.

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
119
120
121
122
123
124
125
126
def get_aliases(self, identifier: str) -> tuple[str, ...]:
    """Get aliases for a given identifier."""
    try:
        data = self._collected[identifier]
    except KeyError:
        return ()
    # Update the following code to return the canonical identifier and any aliases.
    return (data.path,)

get_extended_templates_dirs

get_extended_templates_dirs(handler: str) -> list[Path]

Load template extensions for the given handler, return their templates directories.

Parameters:

  • handler (str) –

    The name of the handler to get the extended templates directory of.

Returns:

  • list[Path] –

    The extensions templates directories.

Source code in mkdocstrings/_internal/handlers/base.py
332
333
334
335
336
337
338
339
340
341
342
def get_extended_templates_dirs(self, handler: str) -> list[Path]:
    """Load template extensions for the given handler, return their templates directories.

    Arguments:
        handler: The name of the handler to get the extended templates directory of.

    Returns:
        The extensions templates directories.
    """
    discovered_extensions = entry_points(group=f"mkdocstrings.{handler}.templates")
    return [extension.load()() for extension in discovered_extensions]

get_headings

get_headings() -> Sequence[Element]

Return and clear the headings gathered so far.

Returns:

Source code in mkdocstrings/_internal/handlers/base.py
485
486
487
488
489
490
491
492
493
def get_headings(self) -> Sequence[Element]:
    """Return and clear the headings gathered so far.

    Returns:
        A list of HTML elements.
    """
    result = list(self._headings)
    self._headings.clear()
    return result

get_inventory_urls

get_inventory_urls() -> list[tuple[str, dict[str, Any]]]

Return the URLs (and configuration options) of the inventory files to download.

Source code in mkdocstrings/_internal/handlers/base.py
215
216
217
def get_inventory_urls(self) -> list[tuple[str, dict[str, Any]]]:
    """Return the URLs (and configuration options) of the inventory files to download."""
    return []

get_options

get_options(local_options: Mapping[str, Any]) -> HandlerOptions

Get combined default, global and local options.

Parameters:

Returns:

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
    """Get combined default, global and local options.

    Arguments:
        local_options: The local options.

    Returns:
        The combined options.
    """
    extra = {
        **self.global_options.get("extra", {}),
        **local_options.get("extra", {}),
    }
    options = {**self.global_options, **local_options, "extra": extra}
    try:
        return ZigOptions.from_data(**options)
    except Exception as error:
        raise PluginError(f"Invalid options: {error}") from error

get_templates_dir

get_templates_dir(handler: str | None = None) -> Path

Return the path to the handler's templates directory.

Override to customize how the templates directory is found.

Parameters:

  • handler (str | None, default: None ) –

    The name of the handler to get the templates directory of.

Raises:

Returns:

  • Path –

    The templates directory path.

Source code in mkdocstrings/_internal/handlers/base.py
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
def get_templates_dir(self, handler: str | None = None) -> Path:
    """Return the path to the handler's templates directory.

    Override to customize how the templates directory is found.

    Arguments:
        handler: The name of the handler to get the templates directory of.

    Raises:
        ModuleNotFoundError: When no such handler is installed.
        FileNotFoundError: When the templates directory cannot be found.

    Returns:
        The templates directory path.
    """
    handler = handler or self.name
    try:
        import mkdocstrings_handlers  # noqa: PLC0415
    except ModuleNotFoundError as error:
        raise ModuleNotFoundError(f"Handler '{handler}' not found, is it installed?") from error

    for path in mkdocstrings_handlers.__path__:
        theme_path = Path(path, handler, "templates")
        if theme_path.exists():
            return theme_path

    raise FileNotFoundError(f"Can't find 'templates' folder for handler '{handler}'")

load_inventory classmethod

load_inventory(in_file: BinaryIO, url: str, base_url: str | None = None, **kwargs: Any) -> Iterator[tuple[str, str]]

Yield items and their URLs from an inventory file streamed from in_file.

Parameters:

  • in_file (BinaryIO) –

    The binary file-like object to read the inventory from.

  • url (str) –

    The URL that this file is being streamed from (used to guess base_url).

  • base_url (str | None, default: None ) –

    The URL that this inventory's sub-paths are relative to.

  • **kwargs (Any, default: {} ) –

    Ignore additional arguments passed from the config.

Yields:

  • tuple[str, str] –

    Tuples of (item identifier, item URL).

Source code in mkdocstrings/_internal/handlers/base.py
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
@classmethod
def load_inventory(
    cls,
    in_file: BinaryIO,  # noqa: ARG003
    url: str,  # noqa: ARG003
    base_url: str | None = None,  # noqa: ARG003
    **kwargs: Any,  # noqa: ARG003
) -> Iterator[tuple[str, str]]:
    """Yield items and their URLs from an inventory file streamed from `in_file`.

    Arguments:
        in_file: The binary file-like object to read the inventory from.
        url: The URL that this file is being streamed from (used to guess `base_url`).
        base_url: The URL that this inventory's sub-paths are relative to.
        **kwargs: Ignore additional arguments passed from the config.

    Yields:
        Tuples of (item identifier, item URL).
    """
    yield from ()

render

render(data: CollectorItem, options: ZigOptions) -> str

Render a template using provided data and configuration options.

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def render(self, data: CollectorItem, options: ZigOptions) -> str:
    """Render a template using provided data and configuration options."""
    # The `data` argument is the data to render, that was collected above in `collect()`.
    # The `options` argument is the configuration options for loading/rendering the data.
    # It contains both the global and local options, combined together.

    # You might want to get the template based on the data type.
    template = self.env.get_template("root.html.jinja")
    # All the following variables will be available in the Jinja templates.
    return template.render(
        config=options,
        data=data,  # You might want to rename `data` into something more specific.
        heading_level=options.heading_level,
        root=True,
    )
render_backlinks(backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -> str

Render backlinks.

Parameters:

  • backlinks (Mapping[str, Iterable[Backlink]]) –

    A mapping of identifiers to backlinks.

  • locale (str | None, default: None ) –

    The locale to use for translations, if any.

Returns:

  • str –

    The rendered backlinks as HTML.

Source code in mkdocstrings/_internal/handlers/base.py
285
286
287
288
289
290
291
292
293
294
295
def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -> str:  # noqa: ARG002
    """Render backlinks.

    Parameters:
        backlinks: A mapping of identifiers to backlinks.
        locale: The locale to use for translations, if any.

    Returns:
        The rendered backlinks as HTML.
    """
    return ""

teardown

teardown() -> None

Teardown the handler.

This method should be implemented to, for example, terminate a subprocess that was started when creating the handler instance.

Source code in mkdocstrings/_internal/handlers/base.py
297
298
299
300
301
302
def teardown(self) -> None:
    """Teardown the handler.

    This method should be implemented to, for example, terminate a subprocess
    that was started when creating the handler instance.
    """

update_env

update_env(config: dict) -> None

Update the Jinja environment with any custom settings/filters/options for this handler.

Parameters:

  • config (dict) –

    MkDocs configuration, read from mkdocs.yml.

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
128
129
130
131
132
133
134
135
136
137
def update_env(self, config: dict) -> None:  # noqa: ARG002
    """Update the Jinja environment with any custom settings/filters/options for this handler.

    Parameters:
        config: MkDocs configuration, read from `mkdocs.yml`.
    """
    self.env.trim_blocks = True
    self.env.lstrip_blocks = True
    self.env.keep_trailing_newline = False
    self.env.filters["markdown"] = markdown.markdown

ZigInputConfig dataclass

ZigInputConfig(options: Annotated[ZigInputOptions, _Field(description='Configuration options for collecting and rendering objects.')] = ZigInputOptions())

Zig handler configuration.

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

Attributes:

  • options (Annotated[ZigInputOptions, _Field(description='Configuration options for collecting and rendering objects.')]) –

    Configuration options for collecting and rendering objects.

options class-attribute instance-attribute

options: Annotated[ZigInputOptions, _Field(description='Configuration options for collecting and rendering objects.')] = field(default_factory=ZigInputOptions)

Configuration options for collecting and rendering objects.

coerce classmethod

coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
183
184
185
186
@classmethod
def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
    """Coerce data."""
    return data

from_data classmethod

from_data(**data: Any) -> Self

Create an instance from a dictionary.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
188
189
190
191
@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    return cls(**cls.coerce(**data))

ZigInputOptions dataclass

ZigInputOptions(extra: Annotated[dict[str, Any], _Field(group='general', description='Extra options.')] = dict(), heading: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated heading of the root object.')] = '', heading_level: Annotated[int, _Field(group='headings', description='The initial heading level to use.')] = 2, show_symbol_type_heading: Annotated[bool, _Field(group='headings', description='Show the symbol type in headings (e.g. mod, class, meth, func and attr).')] = False, show_symbol_type_toc: Annotated[bool, _Field(group='headings', description='Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).')] = False, toc_label: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated toc label of the root object.')] = '')

Accepted input options.

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

Attributes:

  • extra (Annotated[dict[str, Any], _Field(group='general', description='Extra options.')]) –

    Extra options.

  • heading (Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated heading of the root object.')]) –

    A custom string to override the autogenerated heading of the root object.

  • heading_level (Annotated[int, _Field(group='headings', description='The initial heading level to use.')]) –

    The initial heading level to use.

  • show_symbol_type_heading (Annotated[bool, _Field(group='headings', description='Show the symbol type in headings (e.g. mod, class, meth, func and attr).')]) –

    Show the symbol type in headings (e.g. mod, class, meth, func and attr).

  • show_symbol_type_toc (Annotated[bool, _Field(group='headings', description='Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).')]) –

    Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).

  • toc_label (Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated toc label of the root object.')]) –

    A custom string to override the autogenerated toc label of the root object.

extra class-attribute instance-attribute

extra: Annotated[dict[str, Any], _Field(group='general', description='Extra options.')] = field(default_factory=dict)

Extra options.

heading class-attribute instance-attribute

heading: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated heading of the root object.')] = ''

A custom string to override the autogenerated heading of the root object.

heading_level class-attribute instance-attribute

heading_level: Annotated[int, _Field(group='headings', description='The initial heading level to use.')] = 2

The initial heading level to use.

show_symbol_type_heading class-attribute instance-attribute

show_symbol_type_heading: Annotated[bool, _Field(group='headings', description='Show the symbol type in headings (e.g. mod, class, meth, func and attr).')] = False

Show the symbol type in headings (e.g. mod, class, meth, func and attr).

show_symbol_type_toc class-attribute instance-attribute

show_symbol_type_toc: Annotated[bool, _Field(group='headings', description='Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).')] = False

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).

toc_label class-attribute instance-attribute

toc_label: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated toc label of the root object.')] = ''

A custom string to override the autogenerated toc label of the root object.

coerce classmethod

coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
146
147
148
149
@classmethod
def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
    """Coerce data."""
    return data

from_data classmethod

from_data(**data: Any) -> Self

Create an instance from a dictionary.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
151
152
153
154
@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    return cls(**cls.coerce(**data))

ZigOptions dataclass

ZigOptions(extra: Annotated[dict[str, Any], _Field(group='general', description='Extra options.')] = dict(), heading: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated heading of the root object.')] = '', heading_level: Annotated[int, _Field(group='headings', description='The initial heading level to use.')] = 2, show_symbol_type_heading: Annotated[bool, _Field(group='headings', description='Show the symbol type in headings (e.g. mod, class, meth, func and attr).')] = False, show_symbol_type_toc: Annotated[bool, _Field(group='headings', description='Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).')] = False, toc_label: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated toc label of the root object.')] = '')

Bases: ZigInputOptions

Final options passed as template context.

Methods:

  • coerce –

    Create an instance from a dictionary.

  • from_data –

    Create an instance from a dictionary.

Attributes:

  • extra (Annotated[dict[str, Any], _Field(group='general', description='Extra options.')]) –

    Extra options.

  • heading (Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated heading of the root object.')]) –

    A custom string to override the autogenerated heading of the root object.

  • heading_level (Annotated[int, _Field(group='headings', description='The initial heading level to use.')]) –

    The initial heading level to use.

  • show_symbol_type_heading (Annotated[bool, _Field(group='headings', description='Show the symbol type in headings (e.g. mod, class, meth, func and attr).')]) –

    Show the symbol type in headings (e.g. mod, class, meth, func and attr).

  • show_symbol_type_toc (Annotated[bool, _Field(group='headings', description='Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).')]) –

    Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).

  • toc_label (Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated toc label of the root object.')]) –

    A custom string to override the autogenerated toc label of the root object.

extra class-attribute instance-attribute

extra: Annotated[dict[str, Any], _Field(group='general', description='Extra options.')] = field(default_factory=dict)

Extra options.

heading class-attribute instance-attribute

heading: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated heading of the root object.')] = ''

A custom string to override the autogenerated heading of the root object.

heading_level class-attribute instance-attribute

heading_level: Annotated[int, _Field(group='headings', description='The initial heading level to use.')] = 2

The initial heading level to use.

show_symbol_type_heading class-attribute instance-attribute

show_symbol_type_heading: Annotated[bool, _Field(group='headings', description='Show the symbol type in headings (e.g. mod, class, meth, func and attr).')] = False

Show the symbol type in headings (e.g. mod, class, meth, func and attr).

show_symbol_type_toc class-attribute instance-attribute

show_symbol_type_toc: Annotated[bool, _Field(group='headings', description='Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).')] = False

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).

toc_label class-attribute instance-attribute

toc_label: Annotated[str, _Field(group='headings', description='A custom string to override the autogenerated toc label of the root object.')] = ''

A custom string to override the autogenerated toc label of the root object.

coerce classmethod

coerce(**data: Any) -> MutableMapping[str, Any]

Create an instance from a dictionary.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
164
165
166
167
168
@classmethod
def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
    """Create an instance from a dictionary."""
    # Coerce any field into its final form.
    return super().coerce(**data)

from_data classmethod

from_data(**data: Any) -> Self

Create an instance from a dictionary.

Source code in src/mkdocstrings_handlers/zig/_internal/config.py
151
152
153
154
@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    return cls(**cls.coerce(**data))

get_handler

get_handler(handler_config: MutableMapping[str, Any], tool_config: MkDocsConfig, **kwargs: Any) -> ZigHandler

Simply return an instance of ZigHandler.

Parameters:

  • handler_config (MutableMapping[str, Any]) –

    The handler configuration.

  • tool_config (MkDocsConfig) –

    The tool (SSG) configuration.

Returns:

Source code in src/mkdocstrings_handlers/zig/_internal/handler.py
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def get_handler(
    handler_config: MutableMapping[str, Any],
    tool_config: MkDocsConfig,
    **kwargs: Any,
) -> ZigHandler:
    """Simply return an instance of `ZigHandler`.

    Arguments:
        handler_config: The handler configuration.
        tool_config: The tool (SSG) configuration.

    Returns:
        An instance of `ZigHandler`.
    """
    base_dir = Path(tool_config.config_file_path or "./mkdocs.yml").parent
    return ZigHandler(
        config=ZigConfig.from_data(**handler_config),
        base_dir=base_dir,
        **kwargs,
    )