Function reference

sphinxcontrib.doxylink.doxylink.find_url(doc, symbol)

Return the URL for a given symbol.

This is where the magic happens. This function could be a lot more clever. At present it required the passed symbol to be almost exactly the same as the entries in the Doxygen tag file.

Parameters :

doc : xml.etree.ElementTree

The XML DOM object

symbol : string

The symbol to lookup in the file. E.g. something like ‘PolyVox::Array’ or ‘tidyUpMemory’

Returns:

String representing the filename part of the URL

sphinxcontrib.doxylink.doxylink.find_url2(mapping, symbol)

Return the URL for a given symbol.

This is where the magic happens.

Parameters :

mapping : dictionary

A dictionary of the form returned by parse_tag_file()

symbol : string

The symbol to lookup in the file. E.g. something like ‘PolyVox::Array’ or ‘tidyUpMemory’

Returns:

String representing the filename part of the URL

Raises :

LookupError

Raised if the symbol could not be matched in the file

sphinxcontrib.doxylink.doxylink.find_url_classes(mapping, symbol)

Prefer classes over names of constructors

sphinxcontrib.doxylink.doxylink.find_url_piecewise(mapping, symbol)

Match the requested symbol reverse piecewise (split on ::) against the tag names to ensure they match exactly (modulo ambiguity) So, if in the mapping there is PolyVox::Volume::FloatVolume and PolyVox::Volume they would be split into:

['PolyVox', 'Volume', 'FloatVolume'] and ['PolyVox', 'Volume']

and reversed:

['FloatVolume', 'Volume', 'PolyVox'] and ['Volume', 'PolyVox']

and truncated to the shorter of the two:

['FloatVolume', 'Volume'] and ['Volume', 'PolyVox']

If we’re searching for the PolyVox::Volume symbol we would compare:

['Volume', 'PolyVox'] to ['FloatVolume', 'Volume', 'PolyVox'].

That doesn’t match so we look at the next in the mapping:

['Volume', 'PolyVox'] to ['Volume', 'PolyVox'].

Good, so we add it to the list

sphinxcontrib.doxylink.doxylink.find_url_remove_templates(mapping, symbol)

Now, to disambiguate between PolyVox::Array< 1, ElementType >::operator[] and PolyVox::Array::operator[] matching operator[], we will ignore templated (as in C++ templates) tag names by removing names containing <

sphinxcontrib.doxylink.doxylink.parse_tag_file(doc)

Takes in an XML tree from a Doxygen tag file and returns a dictionary that looks something like:

{'PolyVox': {'file': 'namespace_poly_vox.html',
             'kind': 'namespace'},
 'PolyVox::Array': {'file': 'class_poly_vox_1_1_array.html',
                    'kind': 'class'},
 'PolyVox::Array1DDouble': {'file': 'namespace_poly_vox.html#a7a1f5fd5c4f7fbb4258a495d707b5c13',
                            'kind': 'typedef'},
 'PolyVox::Array1DFloat': {'file': 'namespace_poly_vox.html#a879a120e49733eba1905c33f8a7f131b',
                           'kind': 'typedef'},
 'PolyVox::Array1DInt16': {'file': 'namespace_poly_vox.html#aa1463ece448c6ebed55ab429d6ae3e43',
                           'kind': 'typedef'},
 'QScriptContext::throwError': {'arglist': {'( Error error, const QString & text )': 'qscriptcontext.html#throwError',
                                            '( const QString & text )': 'qscriptcontext.html#throwError-2'},
                                'kind': 'function'},
 'QScriptContext::toString': {'arglist': {'()': 'qscriptcontext.html#toString'},
                              'kind': 'function'}}

Note the different form for functions. This is required to allow for ‘overloading by argument type’.

To access a filename for a symbol you do:

symbol_mapping = mapping[symbol]
if symbol_mapping['kind'] == 'function':
        url = symbol_mapping['arglist'][argument_string]
else:
        url = symbol_mapping['file']

Parameters :

doc : xml.etree.ElementTree

The XML DOM object

Returns:

a dictionary mapping fully qualified symbols to files

sphinxcontrib.doxylink.doxylink.return_from_mapping(mapping_entry, normalised_arglist='')

Return a mapping to a single URL in the form. This is needed since mapping entries for functions are more complicated due to function overriding.

If the mapping to be returned is not a function, this will simply return the mapping entry intact. If the entry is a function it will attempt to get the right version based on the function signature.

Parameters :

mapping_entry : dict

should be a single entry from the large mapping file corresponding to a single symbol. If the symbol is a function, then mappingentry['arglist'] will be a dictionary mapping normalised signatures to URLs

normalised_arglist : string

the normalised form of the arglist that the user has requested. This can be empty in which case the function will return just the first element of mappingentry['arglist']. This parameter is ignored if mappingentry['kind'] != 'function'

Returns:

dictionary something like:

{'kind' : 'function', 'file' : 'something.html#foo'}

sphinxcontrib.doxylink.parsing.normalise(symbol)

Takes a c++ symbol or funtion and splits it into symbol and a normalised argument list.

Parameters :

symbol : string

A C++ symbol or function definition like PolyVox::Volume, Volume::printAll() const

Returns:

a tuple consisting of two strings: (qualified function name or symbol, normalised argument list)