gtkdoc.common

gtkdoc.common.CreateValidSGMLID(xml_id)

Creates a valid SGML ‘id’ from the given string.

According to http://www.w3.org/TR/html4/types.html#type-id “ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens (“-“), underscores (“_”), colons (“:”), and periods (“.”).”

When creating SGML IDS, we append “:CAPS” to all all-caps identifiers to prevent name clashes (SGML ids are case-insensitive). (It basically never is the case that mixed-case identifiers would collide.)

Parameters:

id (str) – The text to be converted into a valid SGML id.

Returns:

The converted id.

Return type:

str

gtkdoc.common.GetModuleDocDir(module_name)

Get the docdir for the given module via pkg-config

Parameters:

module_name (string) – The module, e.g. ‘glib-2.0’

Returns:

the doc directory or None

Return type:

str

gtkdoc.common.LogWarning(filename, line, message)

Log a warning in gcc style format

Parameters:

  • file (str) – The file the error comes from

  • line (int) – line number in the file

  • message (str) – the error message to print

gtkdoc.common.ParseEnumDeclaration(declaration)

Parse an enum declaration.

This function takes a enumeration declaration and breaks it into individual enum member declarations.

Parameters:

declaration (str) – the declaration to parse

Returns:

list of strings describing the public declaration

Return type:

str

exception gtkdoc.common.ParseError
gtkdoc.common.ParseFunctionDeclaration(declaration, typefunc, namefunc)

Parse a function declaration.

This function takes a function declaration and breaks it into individual parameter declarations.

Parameters:

  • declaration (str) – the declaration to parse

  • typefunc (func) – function to apply to type

  • namefunc (func) – function to apply to name

Returns:

map of (symbol, decl) pairs describing the prototype

Return type:

dict

gtkdoc.common.ParseMacroDeclaration(declaration, namefunc)

Parse a macro declaration.

This function takes a macro declaration and breaks it into individual parameter declarations.

Parameters:

  • declaration (str) – the declaration to parse

  • namefunc (func) – function to apply to name

Returns:

map of (symbol, decl) pairs describing the macro

Return type:

dict

gtkdoc.common.ParseStructDeclaration(declaration, is_object, output_function_params, typefunc=None, namefunc=None)

Parse a struct declaration.

Takes a structure declaration and breaks it into individual type declarations.

Parameters:

  • declaration (str) – the declaration to parse

  • is_object (bool) – true if this is an object structure

  • output_function_params (bool) – true if full type is wanted for function pointer members

  • typefunc (func) – function to apply to type

  • namefunc (func) – function to apply to name

Returns:

map of (symbol, decl) pairs describing the public declaration

Return type:

dict

gtkdoc.common.PreprocessStructOrEnum(declaration)

Trim a type declaration for display.

Removes private sections and comments from the declaration.

Parameters:

declaration (str) – the type declaration (struct or enum)

Returns:

the trimmed declaration

Return type:

str

gtkdoc.common.UpdateFileIfChanged(old_file, new_file, make_backup)

Compares the old version of the file with the new version and if the file has changed it moves the new version into the old versions place. This is used so we only change files if needed, so we can do proper dependency tracking.

Parameters:

  • old_file (str) – The pathname of the old file.

  • new_file (str) – The pathname of the new version of the file.

  • make_backup (bool) – True if a backup of the old file should be kept. It will have the .bak suffix added to the file name.

Returns:

It returns False if the file hasn’t changed, and True if it has.

Return type:

bool

gtkdoc.common.setup_logging()

Check GTKDOC_TRACE environment variable.

Set python log level to the value of the environment variable (DEBUG, INFO, WARNING, ERROR and CRITICAL) or INFO if the environment variable is empty.