Skip to content

c ¤

C handler for mkdocstrings.

Classes:

  • CConfig –

    C handler configuration.

  • CHandler –

    The C handler class.

  • CInputConfig –

    C handler configuration.

  • CInputOptions –

    Accepted input options.

  • COptions –

    Final options passed as template context.

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

CConfig dataclass ¤

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

Bases: CInputConfig

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

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

CHandler ¤

CHandler(
    config: Mapping[str, Any], base_dir: Path, **kwargs: Any
)

Bases: BaseHandler

The C handler class.

Parameters:

  • config (Mapping[str, Any]) –

    The handler configuration.

  • base_dir (Path) –

    The base directory of the project.

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

    Arguments passed to the parent constructor.

Returned by:

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 –

    Return the possible 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 –

    Combine configuration 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) –

    Fallback configuration when searching anchors for identifiers.

  • fallback_theme (str) –

    The theme to fallback to.

  • global_options –

    The global options for the handler.

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

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 = 'c'

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 = {}

Fallback configuration when searching anchors for identifiers.

fallback_theme class-attribute ¤

fallback_theme: str = 'material'

The theme to fallback to.

global_options instance-attribute ¤

global_options = get('options', {})

The global options for the handler.

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 = 'c'

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: COptions
) -> 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.

  • options (COptions) –

    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.

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.

do_heading ¤

do_heading(
    content: Markup,
    heading_level: int,
    *,
    role: str | None = None,
    hidden: bool = False,
    toc_label: str | None = None,
    **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).

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

    Any extra HTML attributes of the heading.

Returns:

  • Markup –

    An HTML string.

get_aliases ¤

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

Return the possible aliases for a given identifier.

Parameters:

  • identifier (str) –

    The identifier to get the aliases of.

Returns:

  • tuple[str, ...] –

    A tuple of strings - aliases.

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.

get_headings ¤

get_headings() -> Sequence[Element]

Return and clear the headings gathered so far.

Returns:

get_inventory_urls ¤

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

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

get_options ¤

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

Combine configuration options.

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.

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

render ¤

render(data: CodeDoc, options: COptions) -> str

Render a template using provided data and configuration options.

Parameters:

  • data (CodeDoc) –

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

  • options (COptions) –

    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.

render_backlinks(
    backlinks: Mapping[str, Iterable[Backlink]],
) -> str

Render backlinks.

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.

update_env ¤

update_env(config: dict) -> None

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

Parameters:

CInputConfig dataclass ¤

CInputConfig(
    options: Annotated[
        CInputOptions,
        _Field(
            description="Configuration options for collecting and rendering objects."
        ),
    ] = CInputOptions(),
)

C handler configuration.

Subclassed by:

Methods:

  • coerce –

    Coerce data.

  • from_data –

    Create an instance from a dictionary.

Attributes:

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

    Configuration options for collecting and rendering objects.

options class-attribute instance-attribute ¤

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

Configuration options for collecting and rendering objects.

coerce classmethod ¤

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

Coerce data.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

CInputOptions dataclass ¤

CInputOptions(
    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.

Subclassed by:

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.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

COptions dataclass ¤

COptions(
    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: CInputOptions

Final options passed as template context.

Returned by: Used by:

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.

from_data classmethod ¤

from_data(**data: Any) -> Self

Create an instance from a dictionary.

CodeDoc dataclass ¤

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

A parsed C source file.

Used by:

Attributes:

functions instance-attribute ¤

functions: list[DocFunc]

"List of functions in the source file.

global_vars instance-attribute ¤

global_vars: list[DocGlobalVar]

List of global variables in the source file.

macros instance-attribute ¤

macros: list[DocMacro]

List of macros in the source file.

typedefs instance-attribute ¤

typedefs: dict[str, DocType]

List of typedefs in the source file.

Comment dataclass ¤

Comment(text: str, last_line_number: int)

A comment extracted from the source code.

Attributes:

last_line_number instance-attribute ¤

last_line_number: int

The last line number of the comment in the source code.

text instance-attribute ¤

text: str

The text of the comment.

DocFunc dataclass ¤

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

A parsed function.

Attributes:

args instance-attribute ¤

args: list[FuncParam]

The arguments of the function.

doc instance-attribute ¤

doc: Docstring | None

The docstring of the function.

name instance-attribute ¤

name: str

The name of the function.

ret instance-attribute ¤

ret: TypeRef

The return type of the function.

DocGlobalVar dataclass ¤

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

A parsed global variable.

Attributes:

  • doc (Docstring | None) –

    The docstring of the global variable.

  • name (str) –

    The name of the global variable.

  • quals (list[str]) –

    The qualifiers of the global variable.

  • tp (TypeRef) –

    The type reference of the global variable.

doc instance-attribute ¤

doc: Docstring | None

The docstring of the global variable.

name instance-attribute ¤

name: str

The name of the global variable.

quals instance-attribute ¤

quals: list[str]

The qualifiers of the global variable.

tp instance-attribute ¤

tp: TypeRef

The type reference of the global variable.

DocMacro dataclass ¤

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

A parsed macro.

Attributes:

  • content (str | None) –

    The content of the macro.

  • doc (Docstring | None) –

    The docstring of the macro.

  • name (str) –

    The name of the macro.

content instance-attribute ¤

content: str | None

The content of the macro.

doc instance-attribute ¤

doc: Docstring | None

The docstring of the macro.

name instance-attribute ¤

name: str

The name of the macro.

DocType dataclass ¤

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

A parsed typedef.

Used by:

Attributes:

  • doc (Docstring | None) –

    The docstring of the typedef.

  • name (str) –

    The name of the typedef.

  • quals (list[str]) –

    The qualifiers of the typedef.

  • tp (TypeRef) –

    The type reference of the typedef.

doc instance-attribute ¤

doc: Docstring | None

The docstring of the typedef.

name instance-attribute ¤

name: str

The name of the typedef.

quals instance-attribute ¤

quals: list[str]

The qualifiers of the typedef.

tp instance-attribute ¤

tp: TypeRef

The type reference of the typedef.

Docstring dataclass ¤

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

A parsed docstring.

Returned by:

Attributes:

  • desc (str) –

    The description of the docstring.

  • params (list[Param] | None) –

    The parameters of the docstring.

  • ret (str | None) –

    The return value of the docstring.

desc instance-attribute ¤

desc: str

The description of the docstring.

params class-attribute instance-attribute ¤

params: list[Param] | None = None

The parameters of the docstring.

ret class-attribute instance-attribute ¤

ret: str | None = None

The return value of the docstring.

FuncParam dataclass ¤

FuncParam(name: str, tp: TypeRef)

A parameter in a function signature.

Attributes:

  • name (str) –

    The name of the parameter.

  • tp (TypeRef) –

    The type reference of the parameter.

name instance-attribute ¤

name: str

The name of the parameter.

tp instance-attribute ¤

tp: TypeRef

The type reference of the parameter.

InOut ¤

Bases: str, Enum

Enumeration for parameter direction.

Returned by: Used by:

Attributes:

  • IN –

    The parameter is an input.

  • OUT –

    The parameter is an output.

  • UNSPECIFIED –

    The direction is unspecified.

IN class-attribute instance-attribute ¤

IN = 'in'

The parameter is an input.

OUT class-attribute instance-attribute ¤

OUT = 'out'

The parameter is an output.

UNSPECIFIED class-attribute instance-attribute ¤

UNSPECIFIED = 'unspecified'

The direction is unspecified.

Macro dataclass ¤

Macro(text: str, line_number: int)

A macro extracted from the source code.

Attributes:

  • line_number (int) –

    The line number of the macro in the source code.

  • text (str) –

    The text of the macro.

line_number instance-attribute ¤

line_number: int

The line number of the macro in the source code.

text instance-attribute ¤

text: str

The text of the macro.

Param dataclass ¤

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

A parameter in a function signature.

Attributes:

  • desc (str) –

    The description of the parameter.

  • in_out (InOut) –

    The direction of the parameter (input, output, or unspecified).

  • name (str) –

    The name of the parameter.

desc instance-attribute ¤

desc: str

The description of the parameter.

in_out instance-attribute ¤

in_out: InOut

The direction of the parameter (input, output, or unspecified).

name instance-attribute ¤

name: str

The name of the parameter.

SupportsQualsAndType ¤

Bases: Protocol

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

Used by:

Attributes:

quals instance-attribute ¤

quals: list[str]

The qualifiers of the type.

type instance-attribute ¤

type: SupportsQualsAndType | TypeDecl | IdentifierType

The type of the node.

TypeDecl ¤

Bases: str, Enum

Enumeration for type declarations.

Returned by: Used by:

Attributes:

  • ARRAY –

    An array type declaration.

  • FUNCTION –

    A function type declaration.

  • NORMAL –

    A normal type declaration.

  • POINTER –

    A pointer type declaration.

ARRAY class-attribute instance-attribute ¤

ARRAY = 'array'

An array type declaration.

FUNCTION class-attribute instance-attribute ¤

FUNCTION = 'function'

A function type declaration.

NORMAL class-attribute instance-attribute ¤

NORMAL = 'normal'

A normal type declaration.

POINTER class-attribute instance-attribute ¤

POINTER = 'pointer'

A pointer type declaration.

TypeRef dataclass ¤

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

A reference to a type in C.

Returned by: Used by:

Attributes:

decl instance-attribute ¤

decl: TypeDecl

The type declaration of the type reference.

name instance-attribute ¤

name: TypeRef | str

The name of the type reference.

params class-attribute instance-attribute ¤

params: list[TypeRef] | None = None

The parameters of the type reference.

quals instance-attribute ¤

quals: list[str]

The qualifiers of the type reference.

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(
    handler_config: MutableMapping[str, Any],
    tool_config: MkDocsConfig,
    **kwargs: Any,
) -> CHandler

Simply return an instance of CHandler.

Parameters:

  • handler_config (MutableMapping[str, Any]) –

    The handler configuration.

  • tool_config (MkDocsConfig) –

    The tool (SSG) configuration.

Returns:

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.