Skip to content

handler ¤

This module implements a handler for the C language.

Classes:

  • CHandler –

    The C handler class.

  • CodeDoc –

    A parsed C source file.

  • Comment –

    A comment extracted from the source code.

  • DocFunc –

    A parsed function.

  • DocGlobalVar –

    A parsed global variable.

  • DocMacro –

    A parsed macro.

  • DocType –

    A parsed typedef.

  • Docstring –

    A parsed docstring.

  • FuncParam –

    A parameter in a function signature.

  • InOut –

    Enumeration for parameter direction.

  • Macro –

    A macro extracted from the source code.

  • Param –

    A parameter in a function signature.

  • SupportsQualsAndType –

    A protocol for types that can have qualifiers and a type.

  • TypeDecl –

    Enumeration for type declarations.

  • TypeRef –

    A reference to a type in C.

Functions:

CHandler ¤

Bases: BaseHandler

The C handler class.

Methods:

  • collect –

    Collect data given an identifier and selection configuration.

  • render –

    Render a template using provided data and configuration options.

  • update_env –

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

Attributes:

  • default_config (dict) –

    The default configuration options.

  • 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.

  • fallback_config (dict) –

    The configuration used to collect item during autorefs fallback.

  • fallback_theme –

    The theme to fallback to.

  • name (str) –

    The handler's name.

default_config class-attribute ¤

default_config: dict = {
    "show_root_heading": False,
    "show_root_toc_entry": True,
    "show_symbol_type_heading": True,
    "show_symbol_type_toc_entry": True,
    "heading_level": 2,
}

The default configuration options.

Option Type Description Default
show_root_heading bool Show the heading of the object at the root of the documentation tree. False
show_root_toc_entry bool If the root heading is not shown, at least add a ToC entry for it. True
heading_level int The initial heading level to use. 2

domain class-attribute instance-attribute ¤

domain: str = 'c'

The cross-documentation domain/language for this handler.

enable_inventory class-attribute instance-attribute ¤

enable_inventory: bool = False

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

fallback_config class-attribute ¤

fallback_config: dict = {'fallback': True}

The configuration used to collect item during autorefs fallback.

fallback_theme class-attribute instance-attribute ¤

fallback_theme = 'material'

The theme to fallback to.

name class-attribute instance-attribute ¤

name: str = 'c'

The handler's name.

collect ¤

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

Collect data given an identifier and selection configuration.

In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into a Python dictionary for example, though the implementation is completely free.

Parameters:

  • identifier (str) –

    An identifier that was found in a markdown document for which to collect data. For example, in Python, it would be 'mkdocstrings.handlers' to collect documentation about the handlers module. It can be anything that you can feed to the tool of your choice.

  • config (MutableMapping[str, Any]) –

    All configuration options for this handler either defined globally in mkdocs.yml or locally overridden in an identifier block by the user.

Returns:

  • CollectorItem –

    Anything you want, as long as you can feed it to the render method.

render ¤

render(data: CodeDoc, config: Mapping[str, Any]) -> str

Render a template using provided data and configuration options.

Parameters:

  • data (CodeDoc) –

    The data to render that was collected above in collect().

  • config (Mapping[str, Any]) –

    All configuration options for this handler either defined globally in mkdocs.yml or locally overridden in an identifier block by the user.

Returns:

  • str –

    The rendered template as HTML.

update_env ¤

update_env(md: Markdown, config: dict) -> None

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

Parameters:

  • md (Markdown) –

    The Markdown instance. Useful to add functions able to convert Markdown into the environment filters.

  • config (dict) –

    Configuration options for mkdocs and mkdocstrings, read from mkdocs.yml. See the source code of mkdocstrings.plugin.MkdocstringsPlugin.on_config to see what's in this dictionary.

CodeDoc dataclass ¤

CodeDoc(
    macros: list[DocMacro],
    functions: list[DocFunc],
    global_vars: list[DocGlobalVar],
    typedefs: dict[str, DocType],
)

A parsed C source file.

Comment dataclass ¤

Comment(text: str, last_line_number: int)

A comment extracted from the source code.

DocFunc dataclass ¤

DocFunc(
    name: str,
    args: list[FuncParam],
    ret: TypeRef,
    doc: Docstring | None,
)

A parsed function.

DocGlobalVar dataclass ¤

DocGlobalVar(
    name: str,
    tp: TypeRef,
    doc: Docstring | None,
    quals: list[str],
)

A parsed global variable.

DocMacro dataclass ¤

DocMacro(
    name: str, content: str | None, doc: Docstring | None
)

A parsed macro.

DocType dataclass ¤

DocType(
    name: str,
    tp: TypeRef,
    doc: Docstring | None,
    quals: list[str],
)

A parsed typedef.

Docstring dataclass ¤

Docstring(
    desc: str,
    params: list[Param] | None = None,
    ret: str | None = None,
)

A parsed docstring.

FuncParam dataclass ¤

FuncParam(name: str, tp: TypeRef)

A parameter in a function signature.

InOut ¤

Bases: str, Enum

Enumeration for parameter direction.

Macro dataclass ¤

Macro(text: str, line_number: int)

A macro extracted from the source code.

Param dataclass ¤

Param(name: str, desc: str, in_out: InOut)

A parameter in a function signature.

SupportsQualsAndType ¤

Bases: Protocol

A protocol for types that can have qualifiers and a type.

TypeDecl ¤

Bases: str, Enum

Enumeration for type declarations.

TypeRef dataclass ¤

TypeRef(
    name: TypeRef | str,
    decl: TypeDecl,
    quals: list[str],
    params: list[TypeRef] | None = None,
)

A reference to a type in C.

ast_to_decl ¤

ast_to_decl(
    node: SupportsQualsAndType, types: dict[str, DocType]
) -> TypeRef

Convert a pycparser AST node to a TypeRef.

desc ¤

desc(doc: Docstring | None) -> str

Get the description from a docstring.

Parameters:

  • doc (Docstring | None) –

    The docstring to get the description from.

Returns:

  • str –

    The description.

extract_comments ¤

extract_comments(code: str) -> tuple[list[Comment], str]

Extract comments from the source code.

Parameters:

  • code (str) –

    The source code to extract comments from.

Returns:

  • tuple[list[Comment], str] –

    A tuple containing a list of comments and the source code with comments removed.

extract_macros ¤

extract_macros(code: str) -> tuple[list[Macro], str]

Extract macros from the source code.

Parameters:

  • code (str) –

    The source code to extract macros from.

Returns:

  • tuple[list[Macro], str] –

    A tuple containing a list of macros and the source code with macros removed.

get_handler ¤

get_handler(
    theme: str,
    custom_templates: str | None = None,
    config_file_path: str | None = None,
    **config: Any
) -> CHandler

Simply return an instance of CHandler.

Parameters:

  • theme (str) –

    The theme to use when rendering contents.

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

    Directory containing custom templates.

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

    The MkDocs configuration file path.

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

    Configuration passed to the handler.

Returns:

  • CHandler –

    An instance of the handler.

lookup_type_html ¤

lookup_type_html(
    data: CodeDoc, tp: TypeRef, *, name: str | None = None
) -> str

Lookup a type and return an HTML representation.

Parameters:

  • data (CodeDoc) –

    The parsed C source file.

  • tp (TypeRef) –

    The type to lookup.

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

    The name of the type.

Returns:

  • str –

    The HTML representation of the type.

parse_docstring ¤

parse_docstring(content: str) -> Docstring

Parse a docstring.

Parameters:

  • content (str) –

    The content of the docstring.

Returns:

tp_ref_to_str ¤

tp_ref_to_str(ref: TypeRef, qualname: str) -> str

Convert a TypeRef to a string.

Parameters:

  • ref (TypeRef) –

    The TypeRef to convert.

  • qualname (str) –

    The name of the type.

Returns:

  • str –

    The string representation of the TypeRef.

typedef_to_str ¤

typedef_to_str(decl: DocType) -> str

Convert a typedef to a string.

Parameters:

  • decl (DocType) –

    The typedef to convert.

Returns:

  • str –

    The string representation of the typedef.