dOxygen Docstrings

Inserts dOxygen documentation into python docstrings. This is done using the xml export capabilities of dOxygen. The docstrings are inserted into the desc dictionary for each function/class and will then be merged with standard auto-docstrings as well as any user input from sidecar files.

This module is available as an xdress plugin by the name xdress.doxygen.

author:Spencer Lyon <spencerlyon2@gmail.com>

Giving Your Project dOxygen

This plugin works in two phases:

1. It takes user given doxygen settings (with sane defaults if not given) and runs dOxygen on the source project in rc.sourcedir.
2. Alters the description dictionary generated by other xdress plugins (mainly xdress.autodescribe) by inserting dOxygen output as class, method, and function docstrings in the numpydoc format

Usage

The usage of this plugin is very straightforward and comes in two steps:

1. Add xdress.doxygen to the list of plugins in your xdressrc.py
2. Define zero, or more of the (optional) rc variables given below. If These are not defined in xdressrc, the plugin will provide some sane initial values.
   1. doxygen_config: A python dictionary mapping doxygen keys to their desired values. See this page in the dOxygen documentation for more information regarding the possible keys.
   2. doxyfile_name: This is the name that should be given to the doxygen config file. The file will be written out in the directory containing xdressrc.py unless a path is specified for this variable. The path is assumed to be relative to the directory where xdress is run. The default value for this variable is 'doxyfile'.
   3. dox_template_ids: This is list of strings that contain the template identifiers used in the C++ source. This is necessary for docstrings to be inserted for templated functions or classes. The default value is ['T', 'S'].

Note

If you would like to see the default values for doxygen_config, try from xdress.doxygen import default_doxygen_config. The only changes that need to take place are as follows: PROJECT_NAME is assigned to rc.package, INPUT is assigned to rc.sourcedir and OUTPUT_DIRECTORY is assigned to rc.builddir.

The user might accomplish these steps as follows:

plugins = ('xdress.stlwrap', 'xdress.autoall', 'xdress.autodescribe',
           'xdress.doxygen', 'xdress.cythongen')

# Set various doxygen configuration keys
doxygen_config = {'PROJECT_NAME': 'My Awesome Project',
                  'EXTRACT_ALL': False,  # Note usage of python False
                  'GENERATE_DOCBOOK': False,
                  'GENERATE_LATEX': True  # Could be 'YES' or True
                  }

# Write the config file in the build directory
doxyfile_name = './build/the_best_doxyfile'

Warning

The most common issue users make with this plugin is including it in the plugins list in the wrong order. Because xdress tries to execute plugins in the order they are listed in xdressrc, it is important that xdress.doxygen come after xdress.autodescribe, but before xdress.cythongen. autodescribe will ensure that the description dictionary is in place and ready for dOxygen to alter before cythongen has a chance to produce wrapper code.

dOygen API

class xdress.doxygen.XDressPlugin

Add python docstrings (in numpydoc format) from dOxygen markup in the source to the generated cython wrapper.

The __init__() method may take no arguments or keyword arguments.

execute(rc)

Runs doxygen to produce the xml, then parses it and adds docstrings to the desc dictionary.

setup(rc)

Need setup method to get project, output_dir, and src_dir from rc and put them in the default_doxygen_config before running doxygen

xdress.doxygen.class_docstr(class_dict, desc_funcs=False)

Generate the main docstring for a class given a dictionary of the parsed dOxygen xml.

Parameters:

class_dict : dict

This is a dictionary that should be the return value of the function parse_class defined in this module

desc_funcs : bool, optional(default=False)

Whether or not to include the brief description of class methods in the main list of methods.

Returns:

msg : str

The docstring to be inserted into the desc dictionary for the class.

xdress.doxygen.fix_xml_links(file_name)

For some reason I can’t get doxygen to remove hyperlinks to members defined in the same file. This messes up the parsing. To overcome this I will just use a little regex magic to do it myself.

xdress.doxygen.func_docstr(func_dict, is_method=False)

Generate the docstring for a function given a dictionary of the parsed dOxygen xml.

Parameters:

func_dict : dict

This is a dictionary that should be the return value of the function parse_function defined in this module. If this is a class method it can be a sub-dictionary of the return value of the parse_class function.

is_method : bool, optional(default=False)

Whether or not to the function is a class method. If it is, the text will be wrapped 4 spaces earlier to offset additional indentation

Returns:

msg : str

The docstring to be inserted into the desc dictionary for the function.

xdress.doxygen.parse_class(class_dict)

Parses a single class and returns a dictionary of dictionaries containing all the data for that class.

Parameters:

class_dict : dict

A dictionary containing the following keys: [‘file_name’, ‘methods’, ‘vars’]

Returns:

data : dict

A dictionary with all docstrings for instance variables and class methods. This object is structured as follows:

data
    'protected-func'
        'prot_func1'
            arg_string
            args
            briefdescription
            detaileddescription
            ret_type
            definition

    'public-func'
        'pub_func_1'
            arg_string
            args
            briefdescription
            detaileddescription
            ret_type
            definition

    'protected-attrib'
        'prot-attrib1'
            briefdescription
            detaileddescription
            type
            definition

This means that data is a 3-level dictionary. The levels go as follows:

1. data

   • keys: Some of the following (more?): ‘protected-func’, ‘protected-attrib’, ‘public-func’, ‘public-static-attrib’, ‘publib-static-func’, ‘public-type’
   • values: dictionaries of attribute types

2. dictionaries of attribute types

   • keys: attribute names
   • values: attribute dictionaries

3. attribute dictionaries

   • keys: arg_string, args, briefdescription, type, definition detaileddescription,
   • values: objects containing the actual data we care about

Notes

The inner ‘arg_string’ key is only applicable to methods as it contains the function signature for the arguments.

xdress.doxygen.parse_function(func_dict)

Takes a dictionary defining where the xml for the function is, does some function specific parsing and returns a new dictionary with the parsed xml.

xdress.doxygen.parse_index_xml(index_path)

Parses index.xml to get list of dictionaries for class and function names. Each dictionary will have as keys the object (function or class) names and the values will be dictionaries with (at least) key-value pairs representing the .xml file name where the information for that object can be found.

Parameters:

index_path : str

The path to index.xml. This is most likely to be provided by the run control instance.

Returns :

classes : dict

A dictionary of dictionaries, one for each class.

funcs : dict

A dictionary of dictionaries, one for each function.