gtkdoc.mkdb

Creates the DocBook files from the source comments.

gtkdoc.mkdb.AddTreeLineArt(tree)

Generate a line art tree.

Add unicode lineart to a pre-indented string array and returns it as as multiline string.

Parameters:

tree (list) – of indented strings.

Returns:

multiline string with tree line art

Return type:

str

gtkdoc.mkdb.CheckIsObject(name)

Check if symbols is an object.

It uses the global Objects array. Note that the Objects array only contains classes in the current module and their ancestors - not all GObject classes.

Parameters:

name (str) – the object name to check.

Returns:

True if the given name is a GObject or a subclass.

Return type:

bool

gtkdoc.mkdb.ConvertXMLChars(symbol, text)

Escape XML chars.

This is used for text in source code comment blocks, to turn chars which are used in XML into entities, e.g. ‘<’ into &lt;’. Depending on INLINE_MARKUP_MODE, this is done unconditionally or only if the character doesn’t seem to be part of an XML construct (tag or entity reference). :param text: the text to turn into proper XML. :type text: str

Returns:

escaped input

Return type:

str

gtkdoc.mkdb.CreateValidSGML(text)

Turn any chars which are used in XML into entities.

e.g. ‘<’ into ‘&lt;’

Parameters:

text (str) – the text to turn into proper XML.

Returns:

escaped input

Return type:

str

gtkdoc.mkdb.DetermineNamespace(symbols)

Find common set of characters.

Parameters:

symbols (list) – a list of symbols to scan for a common prefix

Returns:

a common namespace prefix (might be empty)

Return type:

str

gtkdoc.mkdb.ExpandAbbreviations(symbol, text)

Expand the shortcut notation for symbol references.

This turns the abbreviations function(), macro(), @param, %constant, and #symbol into appropriate DocBook markup. CDATA sections and <programlisting> parts are skipped.

Parameters:

  • symbol (str) – the symbol being documented, for error messages.

  • text (str) – the text to expand.

Returns:

the expanded text

Return type:

str

gtkdoc.mkdb.ExpandAnnotation(symbol, param_desc)

This turns annotations into acronym tags. :param symbol: the symbol being documented, for error messages. :type symbol: str :param param_desc: the text to expand. :type param_desc: str

Returns:

the remaining param_desc str: the formatted annotations

Return type:

str

gtkdoc.mkdb.GetActions(gobject)

Generate action docs.

Returns the synopsis and detailed description DocBook output for the actions of a given GtkWidget subclass.

Parameters:

object (str) – the GObject subclass, e.g. ‘GtkButton’.

Returns:

action docs

Return type:

str

gtkdoc.mkdb.GetArgs(gobject)

Generate property docs.

Returns the synopsis and detailed description DocBook output for the Args of a given GtkObject subclass.

Parameters:

object (str) – the GObject subclass, e.g. ‘GtkButton’.

Returns:

property docs

Return type:

str

gtkdoc.mkdb.GetDerived(iface)

Returns the DocBook output describing the derived interfaces of an interface. It uses the global %Prerequisites hash.

Parameters:

iface (str) – the interface.

Returns:

derived interfaces

Return type:

str

gtkdoc.mkdb.GetHierarchy(gobject, hierarchy)

Generate the object inheritance graph.

Returns the DocBook output describing the ancestors and immediate children of a GObject subclass. It uses the global Objects and ObjectLevels arrays to walk the tree.

Parameters:

  • object (str) – the GtkObject subclass.

  • hierarchy (list) –

Returns:

lines of docbook describing the hierarchy

Return type:

list

gtkdoc.mkdb.GetImplementations(gobject)

Generate interface usage graph.

Returns the DocBook output describing the implementations of an interface. It uses the global Interfaces hash.

Parameters:

object (str) – the GObject subclass.

Returns:

interface implementations

Return type:

str

gtkdoc.mkdb.GetInterfaces(gobject)

Generate interface implementation graph.

Returns the DocBook output describing the interfaces implemented by a class. It uses the global Interfaces hash.

Parameters:

object (str) – the GObject subclass.

Returns:

implemented interfaces

Return type:

str

gtkdoc.mkdb.GetPrerequisites(iface)

Generates interface requirements.

Returns the DocBook output describing the prerequisites of an interface. It uses the global Prerequisites hash. :param iface: the interface. :type iface: str

Returns:

required interfaces

Return type:

str

gtkdoc.mkdb.GetSignals(gobject)

Generate signal docs.

Returns the synopsis and detailed description DocBook output for the signal handlers of a given GObject subclass.

Parameters:

object (str) – the GObject subclass, e.g. ‘GtkButton’.

Returns:

signal docs

Return type:

str

gtkdoc.mkdb.GetSymbolParams(symbol)

Get the symbol params and check that they are not empty.

If no parameters are filled in, we don’t generate the description table, for backwards compatibility.

Parameters:

symbol – the symbol to check the parameters for

Returns:

The parameters bool: True if empty

Return type:

dict

gtkdoc.mkdb.GetSymbolSourceLocation(symbol)

Get the filename and line where the symbol docs where taken from.

gtkdoc.mkdb.IsEmptyDoc(doc)

Check if a doc-string is empty.

It is also regarded as empty if it only consist of whitespace or e.g. FIXME.

Parameters:

doc (str) – the doc-string

Returns:

True if empty

Return type:

bool

gtkdoc.mkdb.MakeConditionDescription(symbol)

This returns a summary of conditions for the given symbol.

Parameters:

symbol (str) – the symbol to create the summary for.

Returns:

formatted text or empty string if no special conditions apply.

Return type:

str

gtkdoc.mkdb.MakeDeprecationNote(symbol)

This returns a deprecation warning for the given symbol.

Parameters:

symbol (str) – the symbol to try to create a warning for.

Returns:

formatted warning or empty string if symbol is not deprecated

Return type:

str

gtkdoc.mkdb.MakeDocHeader(tag)

Builds a docbook header for the given tag.

Parameters:

tag (str) – doctype tag

Returns:

the docbook header

Return type:

str

gtkdoc.mkdb.MakeIndexterms(symbol, sid)

This returns a indexterm elements for the given symbol

Parameters:

symbol (str) – the symbol to create indexterms for

Returns:

doxbook index terms

Return type:

str

gtkdoc.mkdb.MakeXRef(symbol, text=None)

This returns a cross-reference link to the given symbol.

Though it doesn’t try to do this for a few standard C types that it knows won’t be in the documentation.

Parameters:

  • symbol (str) – the symbol to try to create a XRef to.

  • text (str) – text to put inside the XRef, defaults to symbol

Returns:

a docbook link

Return type:

str

gtkdoc.mkdb.MergeSourceDocumentation()

Merges documentation read from a source file.

Parameter descriptions override any in the template files. Function descriptions are placed before any description from the template files.

gtkdoc.mkdb.ModifyXMLElements(text, symbol, start_tag_regexp, end_tag_func, callback)

Rewrite XML blocks.

Looks for given XML element tags within the text, and calls the callback on pieces of text inside & outside those elements. Used for special handling of text inside things like CDATA and <programlisting>.

Parameters:

  • text (str) – the text.

  • symbol (str) – the symbol currently being documented (only used for error messages).

  • start_tag_regexp (str) – the regular expression to match start tags. e.g. “<![CDATA[|<programlisting[^>]*>” to match CDATA sections or programlisting elements.

  • end_tag_func (func) – function which is passed the matched start tag and should return the appropriate end tag string regexp.

  • is (callback - callback called with each part of the text. It) – called with a piece of text, the symbol being documented, and the matched start tag or ‘’ if the text is outside the XML elements being matched.

Returns:

modified text

Return type:

str

gtkdoc.mkdb.OutputAllSymbols()

Outputs list of all symbols to a file.

gtkdoc.mkdb.OutputAnnotationGlossary()

Writes a glossary of the used annotation terms.

The glossary file can be included into the main document.

gtkdoc.mkdb.OutputBook(main_file, book_top, book_bottom, obj_tree)

Outputs the entities that need to be included into the main docbook file for the module.

Parameters:

  • book_top (str) – the declarations of the entities, which are added at the top of the main docbook file.

  • book_bottom (str) – the entities, which are added in the main docbook file at the desired position.

  • obj_tree (list) – object tree list

gtkdoc.mkdb.OutputDB(file, options)

Generate docbook files.

This collects the output for each section of the docs, and outputs each file when the end of the section is found.

Parameters:

  • file (str) – the $MODULE-sections.txt file which contains all of the functions/macros/structs etc. being documented, organised into sections and subsections.

  • options – commandline options

gtkdoc.mkdb.OutputDBFile(file, title, section_id, includes, functions_synop, other_synop, functions_details, other_desc, signals_synop, signals_desc, args_synop, args_desc, actions_synop, actions_desc, hierarchy, interfaces, implementations, prerequisites, derived, file_objects, default_stability)

Outputs the final DocBook file for one section.

Parameters:

  • file (str) – the name of the file.

  • title (str) – the title from the $MODULE-sections.txt file

  • section_id (str) – the id to use for the toplevel tag.

  • includes (str) – comma-separates list of include files added at top of synopsis, with ‘<’ ‘>’ around them (if not already enclosed in ‘’).

  • functions_synop (str) – the DocBook for the Functions Synopsis part.

  • other_synop (str) – the DocBook for the Types and Values Synopsis part.

  • functions_details (str) – the DocBook for the Functions Details part.

  • other_desc (str) – the DocBook for the Types and Values Details part.

  • signal_synop (str) – the DocBook for the Signal Synopsis part

  • signal_desc (str) – the DocBook for the Signal Description part

  • args_synop (str) – the DocBook for the Arg Synopsis part

  • args_desc (str) – the DocBook for the Arg Description part

  • actions_synop (str) – the DocBook for the Action Synopsis part

  • actions_desc (str) – the DocBook for the Action Description part

  • hierarchy (str) – the DocBook for the Object Hierarchy part

  • interfaces (str) – the DocBook for the Interfaces part

  • implementations (str) – the DocBook for the Known Implementations part

  • prerequisites (str) – the DocBook for the Prerequisites part

  • derived (str) – the DocBook for the Derived Interfaces part

  • file_objects (list) – objects in this file

  • default_stability (str) – fallback if no api-stability is set (optional)

Returns:

True if the docs where updated

Return type:

bool

gtkdoc.mkdb.OutputDeclaration(symbol, declaration)

Returns the formatted documentation block for a symbol.

Parameters:

  • symbol (str) – the name of the function/macro/…

  • declaration (str) – the declaration of the function/macro.

Returns:

the formatted documentation

Return type:

str

gtkdoc.mkdb.OutputEnum(symbol, declaration)

Returns the synopsis and detailed description of a enum.

Parameters:

  • symbol (str) – the enum.

  • declaration (str) – the declaration of the enum.

Returns:

the formatted docs

Return type:

str

gtkdoc.mkdb.OutputExtraFile(file)

Copies an “extra” DocBook file into the output directory, expanding abbreviations.

Parameters:

file (str) – the source file.

Returns:

True if the docs where updated

Return type:

bool

gtkdoc.mkdb.OutputFunction(symbol, declaration, symbol_type)

Returns the synopsis and detailed description of a function.

Parameters:

  • symbol (str) – the function.

  • declaration (str) – the declaration of the function.

Returns:

the formatted docs

Return type:

str

gtkdoc.mkdb.OutputIndex(basename, apiindex)

Writes an index that can be included into the main-document into an <index> tag.

Parameters:

  • basename (str) – name of the index file without extension

  • apiindex (dict) – the index data

gtkdoc.mkdb.OutputMacro(symbol, declaration)

Returns the synopsis and detailed description of a macro.

Parameters:

  • symbol (str) – the macro name.

  • declaration (str) – the declaration of the macro.

Returns:

the formatted docs

Return type:

str

gtkdoc.mkdb.OutputMissingDocumentation()

Outputs report of documentation coverage to a file.

Returns:

True if the report was updated

Return type:

bool

gtkdoc.mkdb.OutputObjectList(obj_list)

This outputs the alphabetical list of objects, in a columned table.

gtkdoc.mkdb.OutputParamDescriptions(symbol_type, symbol, fields)

Returns the DocBook output describing the parameters of a symbol.

This can be used for functions, macros or signal handlers.

Parameters:

  • symbol_type (str) – ‘FUNCTION’, ‘MACRO’ or ‘SIGNAL’. Signal handlers have an implicit user_data parameter last.

  • symbol (str) – the name of the symbol being described.

  • fields (list) – parsed fields from the declaration, used to determine undocumented/unused entries

Returns:

the formatted parameter docs

Return type:

str

gtkdoc.mkdb.OutputProgramDBFile(program, section_id)

Outputs the final DocBook file for one program.

Parameters:

  • file (str) – the name of the file.

  • section_id (str) – the id to use for the toplevel tag.

Returns:

True if the docs where updated

Return type:

bool

gtkdoc.mkdb.OutputSinceIndexes()

Generate the ‘since’ api index files.

gtkdoc.mkdb.OutputStruct(symbol, declaration)

Returns the synopsis and detailed description of a struct.

We check if it is a object struct, and if so we only output parts of it that are noted as public fields. We also use a different IDs for object structs, since the original ID is used for the entire RefEntry.

Parameters:

  • symbol (str) – the struct.

  • declaration (str) – the declaration of the struct.

Returns:

the formatted docs

Return type:

str

Returns extralinks for the symbol (if enabled).

Parameters:

symbol (str) – the name to describe

Returns:

paragraph or empty string

Return type:

str

gtkdoc.mkdb.OutputSymbolTraits(symbol)

Returns the Since and StabilityLevel paragraphs for a symbol.

Parameters:

symbol (str) – the name to describe

Returns:

paragraph or empty string

Return type:

str

gtkdoc.mkdb.OutputSymbolsWithoutSince()

Outputs list of all symbols without a since tag to a file.

gtkdoc.mkdb.OutputTypedef(symbol, declaration)

Returns the synopsis and detailed description of a typedef.

Parameters:

  • symbol (str) – the typedef.

  • declaration (str) – the declaration of the typedef, e.g. ‘typedef unsigned int guint;’

Returns:

the formatted docs

Return type:

str

gtkdoc.mkdb.OutputUndeclaredSymbols()

Reports undeclared symbols.

Outputs symbols that are listed in the section file, but have no declaration in the sources.

Returns:

True if the report was updated

Return type:

bool

gtkdoc.mkdb.OutputUnion(symbol, declaration)

Returns the synopsis and detailed description of a union.

Parameters:

  • symbol (str) – the union.

  • declaration (str) – the declaration of the union.

Returns:

the formatted docs

Return type:

str

gtkdoc.mkdb.OutputUnusedSymbols()

Reports unused documentation.

Outputs symbols that are documented in comments, but not declared in the sources.

Returns:

True if the report was updated

Return type:

bool

gtkdoc.mkdb.OutputVariable(symbol, declaration)

Returns the synopsis and detailed description of a variable.

Parameters:

  • symbol (str) – the extern’ed variable.

  • declaration (str) – the declaration of the variable.

Returns:

the formatted docs

Return type:

str

gtkdoc.mkdb.ParseCommentBlock(lines, line_number=0, ifile='')

Parse a single comment block.

Parameters:

  • lines (list) – the comment block

  • line_number (int) – the first line of the block (for reporting)

  • ifile (str) – file name of the source file (for reporting)

gtkdoc.mkdb.ParseCommentBlockSegments(symbol, segments, params, line_number=0, ifile='')

Parse the comemnts block segments.

Parameters:

  • symbol (str) – the symbol name

  • segments (dict) – the comment block segments (except params)

  • parans (dict) – the comment block params

  • line_number (int) – the first line of the block (for reporting)

  • ifile (str) – file name of the source file (for reporting)

gtkdoc.mkdb.ParseStabilityLevel(stability, file, line, message)

Parses a stability level and outputs a warning if it isn’t valid. :param stability: the stability text. :type stability: str :param file: context for error message :param line: context for error message :param message: description of where the level is from, to use in any error message.

Returns:

the parsed stability level string.

Return type:

str

gtkdoc.mkdb.ReadActionsFile(ifile)

Reads information about object actions

It creates the arrays ActionObjects, ActionNames, ActionParams and ActionProperties containing info on the actions.

Parameters:

ifile (str) – the input filename.

gtkdoc.mkdb.ReadArgsFile(ifile)

Reads information about object properties

It creates the arrays ArgObjects, ArgNames, ArgTypes, ArgFlags, ArgNicks and ArgBlurbs containing info on the args.

Parameters:

ifile (str) – the input filename.

gtkdoc.mkdb.ReadDeclarationsFile(ifile, override)

Reads in a file containing the function/macro/enum etc. declarations.

Note that in some cases there are several declarations with the same name, e.g. for conditional macros. In this case we set a flag in the DeclarationConditional hash so the declaration is not shown in the docs.

If a macro and a function have the same name, e.g. for g_object_ref, the function declaration takes precedence.

Some opaque structs are just declared with ‘typedef struct _name name;’ in which case the declaration may be empty. The structure may have been found later in the header, so that overrides the empty declaration.

Parameters:

  • file (str) – the declarations file to read

  • override (bool) – if declarations in this file should override any current declaration.

gtkdoc.mkdb.ReadInterfaces(ifile)

Reads the $MODULE.interfaces file.

Parameters:

ifile (str) – the input filename.

gtkdoc.mkdb.ReadKnownSymbols(file)

Collect the names of non-private symbols from the $MODULE-sections.txt file.

Parameters:

file – the $MODULE-sections.txt file

gtkdoc.mkdb.ReadObjectHierarchy(ifile)

Reads the $MODULE-hierarchy file.

This contains all the GObject subclasses described in this module (and their ancestors). It places them in the Objects array, and places their level in the object hierarchy in the ObjectLevels array, at the same index. GObject, the root object, has a level of 1.

Parameters:

ifile (str) – the input filename.

gtkdoc.mkdb.ReadPrerequisites(ifile)

This reads in the $MODULE.prerequisites file.

Parameters:

ifile (str) – the input filename.

gtkdoc.mkdb.ReadSignalsFile(ifile)

Reads information about object signals.

It creates the arrays @SignalNames and @SignalPrototypes containing details about the signals. The first line of the SignalPrototype is the return type of the signal handler. The remaining lines are the parameters passed to it. The last parameter, “gpointer user_data” is always the same so is not included.

Parameters:

ifile (str) – the file containing the signal handler prototype information.

gtkdoc.mkdb.ReadSourceDocumentation(source_dir, suffix_list, source_dirs, ignore_files)

Read the documentation embedded in comment blocks in the source code.

It recursively descends the source directory looking for source files and scans them looking for specially-formatted comment blocks.

Parameters:

  • source_dir (str) – the directory to scan.

  • suffix_list (list) – extensions to check

gtkdoc.mkdb.ScanSourceContent(input_lines, ifile='')

Scans the source code lines for specially-formatted comment blocks.

Updates global state in SourceSymbolDocs, SymbolSourceLocation, Since, StabilityLevel, Deprecated, SymbolAnnotations.

Might read from global state in DeclarationTypes

Parameters:

  • input_lines (list) – list of source code lines

  • ifile (str) – file name of the source file (for reporting)

Returns:

tuples with comment block and its starting line

Return type:

list

gtkdoc.mkdb.ScanSourceFile(ifile, ignore_files)

Scans one source file looking for specially-formatted comment blocks.

Later MergeSourceDocumentation() is copying over the doc blobs that are not suppressed/ignored.

Parameters:

ifile (str) – the file to scan.

gtkdoc.mkdb.SegmentCommentBlock(lines, line_number=0, ifile='')

Cut a single comment block into segments.

Parameters:

  • lines (list) – the comment block

  • line_number (int) – the first line of the block (for reporting)

  • ifile (str) – file name of the source file (for reporting)

Returns:

symbol name and dict of comment segments

Return type:

(str, dict)

gtkdoc.mkdb.extract_struct_body(symbol, decl, has_typedef, public)

Returns a normalized struct body.

Normalizes whitespace and newlines and supresses non public members.

Returns:

the nomalized struct declaration

Return type:

str

gtkdoc.mkdb.trim_leading_and_trailing_nl(text)

Trims extra newlines.

Leaves a single trailing newline.

Parameters:

text (str) – the text block to trim. May contain newlines.

Returns:

trimmed text

Return type:

(str)

gtkdoc.mkdb.trim_white_spaces(text)

Trims extra whitespace.

Empty lines inside a block are preserved. All whitespace and the end is replaced with a single newline.

Parameters:

text (str) – the text block to trim. May contain newlines.

Returns:

trimmed text

Return type:

(str)