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.
Giving Your Project dOxygen
This plugin works in two phases:
- It takes user given doxygen settings (with sane defaults if not
given) and runs dOxygen on the source project in rc.sourcedir.
- 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:
- Add xdress.doxygen to the list of plugins in your xdressrc.py
- 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.
- 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.
- 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'.
- 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[source]
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)[source]
Runs doxygen to produce the xml, then parses it and adds
docstrings to the desc dictionary.
-
setup(rc)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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:
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
dictionaries of attribute types
- keys: attribute names
- values: attribute dictionaries
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)[source]
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)[source]
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.
|