hpp2plantuml - Convert C++ header files to PlantUML

[src/hpp2plantuml/hpp2plantuml.py]
# %% Base classes


class Container(object):
    """Base class for C++ objects

    This class defines the basic interface for parsed objects (e.g. class).
    """
    def __init__(self, container_type, name):
        """Class constructor

        Parameters
        ----------
        container_type : str
            String representation of container type (``class``, ``struct`` or
            ``enum``)
        name : str
            Object name (with ``<``, ``>`` characters removed)
        """
        self._container_type = container_type
        self._name = re.sub('[<>]', '', re.sub('-', '_', name))
        self._member_list = []
        self._namespace = ''
        self._parent = None

    @property
    def name(self):
        """Name property accessor

        Returns
        -------
        str
            Object name
        """
        return self._name

    def parse_members(self, header_container):
        """Initialize object from header

        Extract object from CppHeaderParser dictionary representing a class, a
        struct or an enum object.  This extracts the namespace.  Use the
        ``parent`` field to determine is the ``namespace`` description from
        ``CppHeaderParser`` is a parent object (e.g. class) or a proper
        ``namespace``.

        Parameters
        ----------
        header_container : CppClass or CppEnum
            Parsed header for container
        """
        namespace = header_container.get('namespace', '')
        if namespace:
            parent = header_container.get('parent', None)
            # Presence of namespace and parent fields indicates a nested class
            if not parent:
                self._namespace = _cleanup_namespace(namespace)
            else:
                #self._parent = re.sub('[<>]', '', parent['name'])
                self._parent = '::'.join(self._name.split('::')[:-1])
                p = parent
                while p.get('parent') is not None:
                    p = p.get('parent', None)
                self._namespace = p['namespace']
        self._do_parse_members(header_container)

    def _do_parse_members(self, header_container):
        """Initialize object from header (abstract method)

        Extract object from CppHeaderParser dictionary representing a class, a
        struct or an enum object.

        Parameters
        ----------
        header_container : CppClass or CppEnum
            Parsed header for container
        """
        raise NotImplementedError(
            'Derived class must implement :func:`_do_parse_members`.')

    def render(self):
        """Render object to string

        Returns
        -------
        str
            String representation of object following the PlantUML syntax
        """
        container_str = self._render_container_def() + ' {\n'
        for member in self._member_list:
            container_str += '\t' + member.render() + '\n'
        container_str += '}\n'
        return container_str

    def comparison_keys(self):
        """Order comparison key between `ClassRelationship` objects

        Use the parent name, the child name then the link type as successive
        keys.

        Returns
        -------
        list
            `operator.attrgetter` objects for successive fields used as keys
        """
        return self._container_type, self._name

    def sort_members(self):
        """Sort container members

        sort the list of members by type and name
        """
        self._member_list.sort(key=lambda obj: obj.comparison_keys())

    def _render_container_def(self):
        """String representation of object definition

        Return the definition line of an object (e.g. "class MyClass").

        Returns
        -------
        str
            Container type and name as string
        """
        return self._container_type + ' ' + self._name

[src/hpp2plantuml/hpp2plantuml.py]
# %% Object member


class ContainerMember(object):
    """Base class for members of `Container` object

    This class defines the basic interface for object members (e.g. class
    variables, etc.)
    """
    def __init__(self, header_member, **kwargs):
        """Constructor

        Parameters
        ----------
        header_member : str
            Member name
        """
        self._name = header_member
        self._type = None

    def render(self):
        """Render object to string (abstract method)

        Returns
        -------
        str
            String representation of object member following the PlantUML
            syntax
        """
        raise NotImplementedError('Derived class must implement `render`.')

    def comparison_keys(self):
        """Order comparison key between `ClassRelationship` objects

        Use the parent name, the child name then the link type as successive
        keys.

        Returns
        -------
        list
            `operator.attrgetter` objects for successive fields used as keys
        """
        if self._type is not None:
            return self._type, self._name
        else:
            return self._name

[src/hpp2plantuml/hpp2plantuml.py]
# %% Class object


class Class(Container):
    """Representation of C++ class

    This class derived from `Container` specializes the base class to handle
    class definition in C++ headers.

    It supports:

    * abstract and template classes
    * member variables and methods (abstract and static)
    * public, private, protected members (static)
    """
    def __init__(self, header_class):
        """Constructor

        Extract the class name and properties (template, abstract) and
        inheritance.  Then, extract the class members from the header using the
        :func:`parse_members` method.

        Parameters
        ----------
        header_class : tuple(str, CppClass)
            Parsed header for class object (two-element list where the first
            element is the class name and the second element is a CppClass
            object)
        """
        super().__init__(header_class[1]['declaration_method'], header_class[0])
        self._abstract = header_class[1]['abstract']
        self._template_type = None
        if 'template' in header_class[1]:
            self._template_type = _cleanup_single_line(
                header_class[1]['template'])
        self._inheritance_list = [re.sub('<.*>', '', parent['class'])
                                  for parent in header_class[1]['inherits']]
        self.parse_members(header_class[1])

    def _do_parse_members(self, header_class):
        """Initialize class object from header

        This method extracts class member variables and methods from header.

        Parameters
        ----------
        header_class : CppClass
            Parsed header for class
        """
        member_type_map = [
            ['properties', ClassVariable],
            ['methods', ClassMethod]
        ]
        for member_type, member_type_handler in member_type_map:
            for member_prop in MEMBER_PROP_MAP.keys():
                member_list = header_class[member_type][member_prop]
                for header_member in member_list:
                    if not header_member.get('deleted', False):
                        self._member_list.append(
                            member_type_handler(header_member, member_prop))

    def build_variable_type_list(self):
        """Get type of member variables

        This function extracts the type of each member variable.  This is used
        to list aggregation relationships between classes.

        Returns
        -------
        list(str)
            List of types (as string) for each member variable
        """
        variable_type_list = []
        for member in self._member_list:
            if isinstance(member, ClassVariable):
                variable_type_list.append(member.get_type())
        return variable_type_list

    def build_inheritance_list(self):
        """Get inheritance list

        Returns
        -------
        list(str)
            List of class names the current class inherits from
        """
        return self._inheritance_list

    def _render_container_def(self):
        """Create the string representation of the class

        Return the class name with template and abstract properties if
        present.  The output string follows the PlantUML syntax.  Note that
        ``struct`` and ``union`` types are rendered as ``classes``.

        Returns
        -------
        str
            String representation of class
        """
        if self._container_type in ['struct', 'union']:
            container_type = 'class'
        else:
            container_type = self._container_type
        class_str = container_type + ' ' + self._name
        if self._abstract:
            class_str = 'abstract ' + class_str
        if self._template_type is not None:
            class_str += ' <{0}>'.format(self._template_type)
        return class_str

[src/hpp2plantuml/hpp2plantuml.py]
# %% Class member


class ClassMember(ContainerMember):
    """Class member (variable and method) representation

    This class is the base class for class members.  The representation
    includes the member type (variable or method), name, scope (``public``,
    ``private`` or ``protected``) and a static flag.

    """
    def __init__(self, class_member, member_scope='private'):
        """Constructor

        Parameters
        ----------
        class_member : CppVariable or CppMethod
            Parsed member object (variable or method)
        member_scope : str
            Member scope property: ``public``, ``private`` or ``protected``
        """
        super().__init__(class_member['name'])
        self._type = None
        self._static = class_member['static']
        self._scope = member_scope
        self._properties = []

    def render(self):
        """Get string representation of member

        The string representation is with the scope indicator and a static
        keyword when the member is static.  It is postfixed by the type (return
        type for class methods) and additional properties (e.g. ``const``
        methods are flagged with the ``query`` property).  The inner part of
        the returned string contains the variable name and signature for
        methods.  This is obtained using the :func:`_render_name` method.

        Returns
        -------
        str
            String representation of member

        """
        if len(self._properties) > 0:
            props = ' {' + ', '.join(self._properties) + '}'
        else:
            props = ''
        vis = MEMBER_PROP_MAP[self._scope] + \
              ('{static} ' if self._static else '')
        member_str = vis + self._render_name() + \
                     (' : ' + self._type if self._type else '') + \
                     props
        return member_str

    def _render_name(self):
        """Get member name

        By default (for member variables), this returns the member name.
        Derived classes can override this to control the name rendering
        (e.g. add the function prototype for member functions)
        """
        return self._name

[src/hpp2plantuml/hpp2plantuml.py]
# %% Enum object


class Enum(Container):
    """Class representing enum objects

    This class defines a simple object inherited from the base `Container`
    class.  It simply lists enumerated values.
    """
    def __init__(self, header_enum, parent=None):
        """Constructor

        Parameters
        ----------
        header_enum : CppEnum
            Parsed CppEnum object
        """
        super().__init__('enum', header_enum.get('name', 'empty'))
        self.parse_members(header_enum)
        if parent:
            self._parent = parent

    def _do_parse_members(self, header_enum):
        """Extract enum values from header

        Parameters
        ----------
        header_enum : CppEnum
            Parsed `CppEnum` object
        """
        for value in header_enum.get('values', []):
            self._member_list.append(EnumValue(value['name']))


class EnumValue(ContainerMember):
    """Class representing values in enum object

    This class only contains the name of the enum value (the actual integer
    value is ignored).
    """
    def __init__(self, header_value, **kwargs):
        """Constructor

        Parameters
        ----------
        header_value : str
            Name of enum member
        """
        super().__init__(header_value)

    def render(self):
        """Rendering to string

        This method simply returns the variable name

        Returns
        -------
        str
            The enumeration element name
        """
        return self._name

[src/hpp2plantuml/hpp2plantuml.py]
# %% Class object


class Namespace(list):
    """Representation of C++ namespace

    This class lists other containers or namespaces and wraps the rendered
    output in a ``namespace`` block.
    """
    def __init__(self, name, *args):
        """Constructor

        Parameters
        ----------
        name : str
            Namespace name
        """
        self._name = name
        super().__init__(*args)

    def render(self):
        """Render namespace content

        Render the elements and wrap the result in a ``namespace`` block

        Returns
        -------
        str
            String representation of namespace in PlantUML syntax
        """
        return wrap_namespace('\n'.join([c.render()
                                         for c in self]), self._name)

[src/hpp2plantuml/hpp2plantuml.py]
# %% Class connections


class ClassRelationship(object):
    """Base object for class relationships

    This class defines the common structure of class relationship objects.
    This includes a parent/child pair and a relationship type (e.g. inheritance
    or aggregation).
    """
    def __init__(self, link_type, c_parent, c_child):
        """Constructor

        Parameters
        ----------
        link_type : str
            Relationship type: ``inherit`` or ``aggregation``
        c_parent : Container
            Parent container
        c_child : Container
            Child container
        """
        self._parent = c_parent.name
        self._child = c_child.name
        self._link_type = link_type
        self._parent_namespace = c_parent._namespace or ''
        self._child_namespace = c_child._namespace or ''

    def comparison_keys(self):
        """Order comparison key between `ClassRelationship` objects

        Compare alphabetically based on the parent name, the child name then
        the link type.

        Returns
        -------
        list
            `operator.attrgetter` objects for successive fields used as keys
        """
        return self._parent, self._child, self._link_type

    def _render_name(self, class_name, class_namespace):
        """Render class name with namespace prefix if necessary

        Parameters
        ----------
        class_name : str
           Name of the class
        class_namespace : str
            Namespace or None if the class is defined in the default namespace

        Returns
        -------
        str
            Class name with appropriate prefix for use with link rendering
        """
        return get_namespace_link_name(class_namespace) + '.' + class_name

    def render(self):
        """Render class relationship to string

        This method generically appends the parent name, a rendering of the
        link type (obtained from the :func:`_render_link_type` method) and the
        child object name.

        Returns
        -------
        str
            The string representation of the class relationship following the
            PlantUML syntax
        """
        link_str = ''

        # Prepend the namespace to the class name
        parent_str = self._render_name(self._parent, self._parent_namespace)
        child_str = self._render_name(self._child, self._child_namespace)

        # Link string
        link_str += (parent_str + ' ' + self._render_link_type() + ' ' +
                     child_str + '\n')

        return link_str

    def _render_link_type(self):
        """Internal representation of link

        The string representation is obtained from the `LINK_TYPE_MAP`
        constant.

        Returns
        -------
        str
            The link between parent and child following the PlantUML syntax
        """
        return LINK_TYPE_MAP[self._link_type]

# Create object
diag = Diagram()
# Initialize from filename
diag.create_from_file(filename)
# Get output string following PlantUML syntax
output_string = diag.render()

[src/hpp2plantuml/hpp2plantuml.py]
# %% Diagram class


class Diagram(object):
    """UML diagram object

    This class lists the objects in the set of files considered, and the
    relationships between object.

    The main interface to the `Diagram` object is via the ``create_*`` and
    ``add_*`` methods.  The former parses objects and builds relationship lists
    between the different parsed objects.  The latter only parses objects and
    does not builds relationship lists.

    Each method has versions for file and string inputs and folder string lists
    and file lists inputs.
    """
    def __init__(self, template_file=None, flag_dep=False):
        """Constructor

        The `Diagram` class constructor simply initializes object lists.  It
        does not create objects or relationships.
        """
        self._flag_dep = flag_dep
        self.clear()
        loader_list = []
        if template_file is not None:
            loader_list.append(jinja2.FileSystemLoader(
                os.path.abspath(os.path.dirname(template_file))))
            self._template_file = os.path.basename(template_file)
        else:
            self._template_file = 'default.puml'
        loader_list.append(jinja2.PackageLoader('hpp2plantuml', 'templates'))
        self._env = jinja2.Environment(loader=jinja2.ChoiceLoader(
            loader_list), keep_trailing_newline=True)

    def clear(self):
        """Reinitialize object"""
        self._objects = []
        self._inheritance_list = []
        self._aggregation_list = []
        self._dependency_list = []
        self._nesting_list = []

    def _sort_list(input_list):
        """Sort list using `ClassRelationship` comparison

        Parameters
        ----------
        input_list : list(ClassRelationship)
            Sort list using the :func:`ClassRelationship.comparison_keys`
            comparison function
        """
        input_list.sort(key=lambda obj: obj.comparison_keys())

    def sort_elements(self):
        """Sort elements in diagram

        Sort the objects and relationship links.  Objects are sorted using the
        :func:`Container.comparison_keys` comparison function and list are
        sorted using the `_sort_list` helper function.
        """
        self._objects.sort(key=lambda obj: obj.comparison_keys())
        for obj in self._objects:
            obj.sort_members()
        Diagram._sort_list(self._inheritance_list)
        Diagram._sort_list(self._aggregation_list)
        Diagram._sort_list(self._dependency_list)
        Diagram._sort_list(self._nesting_list)

    def _build_helper(self, data_in, build_from='string', flag_build_lists=True,
                      flag_reset=False):
        """Helper function to initialize a `Diagram` object from parsed headers

        Parameters
        ----------
        data_in : CppHeader or str or list(CppHeader) or list(str)
            Input of arbitrary type.  The processing depends on the
            ``build_from`` parameter
        build_from : str
            Determines the type of the ``data_in`` variable:

            * ``string``: ``data_in`` is a string containing C++ header code
            * ``file``: ``data_in`` is a filename to parse
            * ``string_list``: ``data_in`` is a list of strings containing C++
              header code
            * ``file_list``: ``data_in`` is a list of filenames to parse

        flag_build_lists : bool
            When True, relationships lists are built and the objects in the
            diagram are sorted, otherwise, only object parsing is performed
        flag_reset : bool
            If True, the object is initialized (objects and relationship lists
            are cleared) prior to parsing objects, otherwise, new objects are
            appended to the list of existing ones
        """
        if flag_reset:
            self.clear()
        if build_from in ('string', 'file'):
            self.parse_objects(data_in, build_from)
        elif build_from in ('string_list', 'file_list'):
            build_from_single = re.sub('_list$', '', build_from)
            for single_input in data_in:
                self.parse_objects(single_input, build_from_single)
        if flag_build_lists:
            self.build_relationship_lists()
            self.sort_elements()

    def create_from_file(self, header_file):
        """Initialize `Diagram` object from header file

        Wrapper around the :func:`_build_helper` function, with ``file`` input,
        building the relationship lists and with object reset.
        """
        self._build_helper(header_file, build_from='file',
                           flag_build_lists=True, flag_reset=True)

    def create_from_file_list(self, file_list):
        """Initialize `Diagram` object from list of header files

        Wrapper around the :func:`_build_helper` function, with ``file_list``
        input, building the relationship lists and with object reset.
        """
        self._build_helper(file_list, build_from='file_list',
                           flag_build_lists=True, flag_reset=True)

    def add_from_file(self, header_file):
        """Augment `Diagram` object from header file

        Wrapper around the :func:`_build_helper` function, with ``file`` input,
        skipping building of the relationship lists and without object reset
        (new objects are added to the object).
        """
        self._build_helper(header_file, build_from='file',
                           flag_build_lists=False, flag_reset=False)

    def add_from_file_list(self, file_list):
        """Augment `Diagram` object from list of header files

        Wrapper around the :func:`_build_helper` function, with ``file_list``
        input, skipping building of the relationship lists and without object
        reset (new objects are added to the object).
        """
        self._build_helper(file_list, build_from='file_list',
                           flag_build_lists=False, flag_reset=False)

    def create_from_string(self, header_string):
        """Initialize `Diagram` object from header string

        Wrapper around the :func:`_build_helper` function, with ``string``
        input, building the relationship lists and with object reset.
        """
        self._build_helper(header_string, build_from='string',
                           flag_build_lists=True, flag_reset=True)

    def create_from_string_list(self, string_list):
        """Initialize `Diagram` object from list of header strings

        Wrapper around the :func:`_build_helper` function, with ``string_list``
        input, skipping building of the relationship lists and with object
        reset.
        """
        self._build_helper(string_list, build_from='string_list',
                           flag_build_lists=True, flag_reset=True)

    def add_from_string(self, header_string):
        """Augment `Diagram` object from header string

        Wrapper around the :func:`_build_helper` function, with ``string``
        input, skipping building of the relationship lists and without object
        reset (new objects are added to the object).
        """
        self._build_helper(header_string, build_from='string',
                           flag_build_lists=False, flag_reset=False)

    def add_from_string_list(self, string_list):
        """Augment `Diagram` object from list of header strings

        Wrapper around the :func:`_build_helper` function, with ``string_list``
        input, building the relationship lists and without object reset (new
        objects are added to the object).
        """
        self._build_helper(string_list, build_from='string_list',
                           flag_build_lists=False, flag_reset=False)

    def build_relationship_lists(self):
        """Build inheritance and aggregation lists from parsed objects

        This method successively calls the :func:`build_inheritance_list` and
        :func:`build_aggregation_list` methods.
        """
        self.build_inheritance_list()
        self.build_aggregation_list()
        self.build_nesting_list()
        if self._flag_dep:
            self.build_dependency_list()

    def parse_objects(self, header_file, arg_type='string'):
        """Parse objects

        This method parses file of string inputs using the CppHeaderParser
        module and extracts internal objects for rendering.

        Parameters
        ----------
        header_file : str
            A string containing C++ header code or a filename with C++ header
            code
        arg_type : str
            If set to ``string``, ``header_file`` is considered to be a string,
            otherwise, it is assumed to be a filename
        """
        # Parse header file
        parsed_header = CppHeaderParser.CppHeader(header_file,
                                                  argType=arg_type)
        for container_type, (container_iterator,
                             container_handler) in CONTAINER_TYPE_MAP.items():
            objects = parsed_header.__getattribute__(container_type)
            for obj in container_iterator(objects):
                # Parse container
                obj_c = container_handler(obj)
                self._objects.append(obj_c)
                # Look for nested enums
                # Find value from iterator (may be a tuple)
                if isinstance(obj, tuple) and len(obj) == 2:
                    obj_n = obj[-1]
                else:
                    obj_n = obj
                if 'enums' in obj_n:
                    for m in MEMBER_PROP_MAP.keys():
                        for enum in obj_n['enums'][m]:
                            enum_c = Enum(enum, parent=obj_c.name)
                            # Adjust name to reflect nesting
                            enum_c._name = obj_c.name + '::' + enum_c._name
                            self._objects.append(enum_c)

    def _make_class_list(self):
        """Build list of classes

        Returns
        -------
        list(dict)
            Each entry is a dictionary with keys ``name`` (class name) and
            ``obj`` the instance of the `Class` class
        """
        return [{'name': obj.name, 'obj': obj}
                for obj in self._objects if isinstance(obj, (Class, Enum))]

    def _get_class_list(self):
        """Build list of classes in diagram

        Returns
        -------
        list
            Class object list (returned by :func:`_make_class_list`)
        list
            Class names
        bool
            True when at least one container is a namespace
        """
        class_list_obj = self._make_class_list()
        class_list = [c['name'] for c in class_list_obj]
        return class_list_obj, class_list

    def build_inheritance_list(self):
        """Build list of inheritance between objects

        This method lists all the inheritance relationships between objects
        contained in the `Diagram` object (external relationships are ignored).

        The implementation establishes a list of available classes and loops
        over objects to obtain their inheritance.  When parent classes are in
        the list of available classes, a `ClassInheritanceRelationship` object
        is added to the list.
        """
        self._inheritance_list = []
        # Build list of classes in diagram
        class_list_obj, class_list = self._get_class_list()

        # Create relationships

        # Inheritance
        for obj in self._objects:
            obj_name = obj.name
            if isinstance(obj, Class):
                for parent in obj.build_inheritance_list():
                    if parent in class_list:
                        parent_obj = class_list_obj[
                            class_list.index(parent)]['obj']
                        self._inheritance_list.append(
                            ClassInheritanceRelationship(
                                parent_obj, obj))

    def build_aggregation_list(self):
        """Build list of aggregation relationships

        This method loops over objects and finds members with type
        corresponding to other classes defined in the `Diagram` object (keeping
        a count of occurrences).

        The procedure first builds an internal dictionary of relationships
        found, augmenting the count using the :func:`_augment_comp` function.
        In a second phase, `ClassAggregationRelationship` objects are created
        for each relationships, using the calculated count.
        """
        self._aggregation_list = []
         # Build list of classes in diagram
        class_list_obj, class_list = self._get_class_list()

        # Build member type list
        variable_type_list = {}
        for obj in self._objects:
            obj_name = obj.name
            if isinstance(obj, Class):
                variable_type_list[obj_name] = obj.build_variable_type_list()
        # Create aggregation links
        aggregation_counts = {}

        for child_class in class_list:
            if child_class in variable_type_list.keys():
                var_types = variable_type_list[child_class]
                for var_type in var_types:
                    for parent in class_list:
                        if re.search(r'\b' + parent + r'\b', var_type):
                            rel_type = 'composition'
                            if '{}*'.format(parent) in var_type:
                                rel_type = 'aggregation'
                            self._augment_comp(aggregation_counts, parent,
                                               child_class, rel_type=rel_type)
        for obj_class, obj_comp_list in aggregation_counts.items():
            for comp_parent, rel_type, comp_count in obj_comp_list:
                obj_class_idx = class_list.index(obj_class)
                obj_class_obj = class_list_obj[obj_class_idx]['obj']
                comp_parent_idx = class_list.index(comp_parent)
                comp_parent_obj = class_list_obj[comp_parent_idx]['obj']
                self._aggregation_list.append(
                    ClassAggregationRelationship(
                        obj_class_obj, comp_parent_obj, comp_count,
                        rel_type=rel_type))

    def build_dependency_list(self):
        """Build list of dependency between objects

        This method lists all the dependency relationships between objects
        contained in the `Diagram` object (external relationships are ignored).

        The implementation establishes a list of available classes and loops
        over objects, list their methods adds a dependency relationship when a
        method takes an object as input.
        """

        self._dependency_list = []
        class_list_obj, class_list = self._get_class_list()

        # Create relationships

        # Add all objects name to list
        objects_name = []
        for obj in self._objects:
            objects_name.append(obj.name)

        # Dependency
        for obj in self._objects:
            if isinstance(obj, Class):
                for member in obj._member_list:
                    # Check if the member is a method
                    if isinstance(member, ClassMethod):
                        for method in member._param_list:
                            index = ValueError
                            try:
                                # Check if the method param type is a Class
                                # type
                                index = [re.search(o, method[0]) is not None
                                         for o in objects_name].index(True)
                            except ValueError:
                                pass
                            if index != ValueError and method[0] != obj.name:
                                depend_obj = self._objects[index]

                                self._dependency_list.append(
                                    ClassDependencyRelationship(
                                        depend_obj, obj))

    def build_nesting_list(self):
        """Build list of nested objects

        """
        self._nesting_list = []
        # Build list of classes in diagram
        class_list_obj, class_list = self._get_class_list()

        for obj in self._objects:
            obj_name = obj.name
            if isinstance(obj, (Class, Enum)):
                parent = obj._parent
                if parent and parent in class_list:
                    parent_obj = class_list_obj[
                        class_list.index(parent)]['obj']
                    self._nesting_list.append(
                        ClassNestingRelationship(
                            parent_obj, obj))

    def _augment_comp(self, c_dict, c_parent, c_child, rel_type='aggregation'):
        """Increment the aggregation reference count

        If the aggregation relationship is not in the list (``c_dict``), then
        add a new entry with count 1.  If the relationship is already in the
        list, then increment the count.

        Parameters
        ----------
        c_dict : dict
            List of aggregation relationships.  For each dictionary key, a pair
            of (str, int) elements: string and number of occurrences
        c_parent : str
            Parent class name
        c_child : str
            Child class name
        rel_type : str
            Relationship type: ``aggregation`` or ``composition``
        """
        if c_child not in c_dict:
            c_dict[c_child] = [[c_parent, rel_type, 1], ]
        else:
            parent_list = [c[:2] for c in c_dict[c_child]]
            if [c_parent, rel_type] not in parent_list:
                c_dict[c_child].append([c_parent, rel_type, 1])
            else:
                c_idx = parent_list.index([c_parent, rel_type])
                c_dict[c_child][c_idx][2] += 1

    def render(self):
        """Render full UML diagram

        The string returned by this function should be ready to use with the
        PlantUML program.  It includes all the parsed objects with their
        members, and the inheritance and aggregation relationships extracted
        from the list of objects.

        Returns
        -------
        str
            String containing the full string representation of the `Diagram`
            object, including objects and object relationships
        """
        template = self._env.get_template(self._template_file)
        # List namespaces
        ns_list = []
        for obj in self._objects:
            if obj._namespace and obj._namespace not in ns_list:
                ns_list.append(obj._namespace)
        # Ensure nested namespaces are processed first
        ns_list = sorted(ns_list, key=lambda ns: len(ns.split('::')),
                         reverse=True)
        # Create namespace objects (flat map)
        ns_obj_map = {ns: Namespace(ns) for ns in ns_list}
        # Build list of objects
        objects_out = []
        # 1. Place objects in namespace container or in output list
        for obj in self._objects:
            if obj._namespace:
                ns_obj_map[obj._namespace].append(obj)
            else:
                objects_out.append(obj)
        # 2. Add namespaces: collapse nested namespaces and add top level
        # namespaces to output list
        for ns in ns_list:
            ns_name_parts = ns.split('::')
            if len(ns_name_parts) > 1:
                ns_parent = '::'.join(ns_name_parts[:-1])
                ns_obj_map[ns_parent].append(ns_obj_map[ns])
            else:
                objects_out.append(ns_obj_map[ns])
        # Render
        return template.render(objects=objects_out,
                               inheritance_list=self._inheritance_list,
                               aggregation_list=self._aggregation_list,
                               dependency_list=self._dependency_list,
                               nesting_list=self._nesting_list,
                               flag_dep=self._flag_dep)

[src/hpp2plantuml/hpp2plantuml.py]
# %% Cleanup object type string


def _cleanup_type(type_str):
    """Cleanup string representing a C++ type

    Cleanup simply consists in removing spaces before a ``*`` character and
    preventing multiple successive spaces in the string.

    Parameters
    ----------
    type_str : str
        A string representing a C++ type definition

    Returns
    -------
    str
        The type string after cleanup
    """
    return re.sub('\s*([<>])\s*', r'\1',
                  re.sub(r'[ ]+([*&])', r'\1',
                         re.sub(r'(\s)+', r'\1', type_str)))

def _cleanup_namespace(ns_str):
    """Cleanup string representing a C++ namespace

    Cleanup simply consists in removing ``<>`` blocks and trailing ``:``
    characters.

    Parameters
    ----------
    ns_str : str
        A string representing a C++ namespace

    Returns
    -------
    str
        The namespace string after cleanup
    """
    return re.sub(':+$', '',
                  re.sub('<([^>]+)>', r'\1',
                         re.sub('(.+)<[^>]+>', r'\1', ns_str)))

[src/hpp2plantuml/hpp2plantuml.py]
# %% Single line version of string


def _cleanup_single_line(input_str):
    """Cleanup string representing a C++ type

    Remove line returns

    Parameters
    ----------
    input_str : str
        A string possibly spreading multiple lines

    Returns
    -------
    str
        The type string in a single line
    """
    return re.sub(r'\s+', ' ', re.sub(r'(\r)?\n', ' ', input_str))

[src/hpp2plantuml/hpp2plantuml.py]
# %% Expand wildcards in file list


def expand_file_list(input_files):
    """Find all files in list (expanding wildcards)

    This function uses `glob` to find files matching each string in the input
    list.

    Parameters
    ----------
    input_files : list(str)
        List of strings representing file names and possibly including
        wildcards

    Returns
    -------
    list(str)
        List of filenames (with wildcards expanded).  Each element contains the
        name of an existing file
    """
    file_list = []
    for input_file in input_files:
        file_list += glob.glob(input_file, recursive=True)
    return file_list

[src/hpp2plantuml/hpp2plantuml.py]
def wrap_namespace(input_str, namespace):
    """Wrap string in namespace

    Parameters
    ----------
    input_str : str
        String containing PlantUML code
    namespace : str
       Namespace name

    Returns
    -------
    str
        ``input_str`` wrapped in ``namespace`` block
    """
    return 'namespace {} {{\n'.format(namespace) + \
        '\n'.join([re.sub('^', '\t', line) if line else line
                   for line in input_str.splitlines()]) + \
        '\n}\n'

def get_namespace_link_name(namespace):
    """Generate namespace string for link

    Parameters
    ----------
    namespace : str
        Namespace name (in the form ``nested::ns``)

    Returns
    -------
    str
        The namespace name formatted for use in links
        (e.g. ``nested.nested::ns``)
    """
    if not namespace:
        return ''
    ns_list = namespace.split('::')
    ns_list_out = [ns_list[0], ]
    for ni, ns in enumerate(ns_list[1:]):
        ns_list_out.append('{}::{}'.format(ns_list_out[ni - 1], ns))
    return '.'.join(ns_list_out)

[tests/test_hpp2plantuml.py]
# %% Test containers


class TestContainer:
    def test_init(self):
        c_type = "container_type"
        c_name = "container_name"
        c_obj = hpp2plantuml.hpp2plantuml.Container(c_type, c_name)
        nt.assert_equal(c_obj.name, c_name)
        nt.assert_equal(c_obj.render(), 'container_type container_name {\n}\n')

    def test_comparison_keys(self):
        c_list = [
            ['class', 'ABD'],
            ['enum', 'ABDa'],
            ['class', 'abcd'],
        ]
        ref_sort_idx = [0, 2, 1]
        c_obj_list = []
        for c_type, c_name in c_list:
            c_obj_list.append(hpp2plantuml.hpp2plantuml.Container(
                c_type, c_name))
        c_obj_list.sort(key=lambda obj: obj.comparison_keys())

        for i in range(len(c_list)):
            nt.assert_equal(c_obj_list[i].name,
                            c_list[ref_sort_idx[i]][1])

[tests/test_hpp2plantuml.py]
# %% Test enum objects


class TestEnum:
    def test_list_entries(self):
        for test_idx, (input_str, output_ref_str) in \
            enumerate(fix_test_list_def(test_list_enum)):
            p = get_parsed_element(input_str)
            enum_name = re.sub(r'.*enum\s*(\w+).*', r'\1',
                               input_str.replace('\n', ' '))
            enum_input = p.enums[0]
            obj_c = hpp2plantuml.hpp2plantuml.Enum(enum_input)
            nt.assert_equal(output_ref_str, obj_c.render(),
                            'Test {0} failed [input: {1}]'.format(test_idx,
                                                                  input_str))

[tests/test_hpp2plantuml.py]
class TestLink:
    def test_list_entries(self):
        for test_idx, (input_str, output_ref_str) in \
            enumerate(fix_test_list_def(test_list_link)):
            obj_d = hpp2plantuml.Diagram(flag_dep=True)
            # Not very unittest-y
            obj_d.create_from_string(input_str)
            if len(obj_d._inheritance_list) > 0:
                obj_l = obj_d._inheritance_list[0]
            elif len(obj_d._aggregation_list) > 0:
                obj_l = obj_d._aggregation_list[0]
            elif len(obj_d._dependency_list) > 0:
                obj_l = obj_d._dependency_list[0]
            nt.assert_equal(output_ref_str, obj_l.render(),
                            'Test {0} failed [input: {1}]'.format(test_idx,
                                                                  input_str))

[tests/simple_classes_1_2.hpp]
enum Enum01 { VALUE_0, VALUE_1, VALUE_2 };

class Class01 {
protected:
    int _protected_var;
    bool _ProtectedMethod(int param);
    static bool _StaticProtectedMethod(bool param);
    virtual bool _AbstractMethod(int param) = 0;
public:
    Class01& operator=(const Class01&) & = delete;
    int public_var;
    bool PublicMethod(int param) const;
    static bool StaticPublicMethod(bool param);
    virtual bool AbstractPublicMethod(int param) = 0;
};

class Class02 : public Class01 {
public:
    bool AbstractPublicMethod(int param) override;
private:
    class ClassNested {
        int var;
    };
    int _private_var;
    template <typename T>
    bool _PrivateMethod(T param);
    static bool _StaticPrivateMethod(bool param);
    bool _AbstractMethod(int param) override;
};

[tests/simple_classes_3.hpp]
template<typename T>
class Class03 {
public:
    Class03();
    ~Class03();
    void Method(Interface::Class04& c4);
private:
    Class01* _obj;
    Class01* _data;
    list<Class02> _obj_list;
    T* _typed_obj;
};

namespace Interface {

    class Class04 {
    public:
        Class04();
        ~Class04();
    private:
        bool _flag;
        Class01* _obj;
        T _var;
        Enum01 _val;
    };

    class Class04_derived : public Class04 {
    public:
        Class04_derived();
        ~Class04_derived();
    private:
        int _var;
    };

    struct Struct {
        int a;
    };
    enum Enum { A, B };

    namespace NestedNamespace {
        class Class04_ns : private Class04_derived {
        protected:
            Struct _s;
            Enum _e;
        };
    };
};

// Anonymous union (issue #9)
union {
    struct {
        float x;
        float y;
        float z;
    };
    struct {
        float rho;
        float theta;
        float phi;
    };
    float vec[3];
};

[tests/simple_classes.puml]
@startuml





/' Objects '/

abstract class Class01 {
        +{abstract} AbstractPublicMethod(int param) : bool
        +PublicMethod(int param) : bool {query}
        +{static} StaticPublicMethod(bool param) : bool
        #{abstract} _AbstractMethod(int param) : bool
        #_ProtectedMethod(int param) : bool
        #{static} _StaticProtectedMethod(bool param) : bool
        #_protected_var : int
        +public_var : int
}


class Class02 {
        +AbstractPublicMethod(int param) : bool
        -_AbstractMethod(int param) : bool
        -_PrivateMethod(T param) : bool
        -{static} _StaticPrivateMethod(bool param) : bool
        -_private_var : int
}


class Class02::ClassNested {
        -var : int
}


class Class03 <template<typename T>> {
        +Class03()
        +~Class03()
        -_data : Class01*
        -_obj : Class01*
        -_typed_obj : T*
        -_obj_list : list<Class02>
        +Method(Interface::Class04& c4) : void
}


enum Enum01 {
        VALUE_0
        VALUE_1
        VALUE_2
}


class anon_union_1::anon_struct_1 {
        +x : float
        +y : float
        +z : float
}


class anon_union_1::anon_struct_2 {
        +phi : float
        +rho : float
        +theta : float
}


class anon_union_1 {
        +vec : float
}


namespace Interface {
        class Class04 {
                +Class04()
                +~Class04()
                -_obj : Class01*
                -_val : Enum01
                -_var : T
                -_flag : bool
        }

        class Class04_derived {
                +Class04_derived()
                +~Class04_derived()
                -_var : int
        }

        enum Enum {
                A
                B
        }

        class Struct {
                +a : int
        }

        namespace Interface::NestedNamespace {
                class Class04_ns {
                        #_e : Enum
                        #_s : Struct
                }
        }
}





/' Inheritance relationships '/

.Class01 <|-- .Class02


Interface.Class04 <|-- Interface.Class04_derived


Interface.Class04_derived <|-- Interface.Interface::NestedNamespace.Class04_ns





/' Aggregation relationships '/

.Class03 "2" o-- .Class01


.Class03 *-- .Class02


Interface.Class04 o-- .Class01


Interface.Class04 *-- .Enum01


Interface.Interface::NestedNamespace.Class04_ns *-- Interface.Enum


Interface.Interface::NestedNamespace.Class04_ns *-- Interface.Struct






/' Dependency relationships '/

Interface.Class04 <.. .Class03






/' Nested objects '/

.Class02 +-- .Class02::ClassNested


.anon_union_1 +-- .anon_union_1::anon_struct_1


.anon_union_1 +-- .anon_union_1::anon_struct_2




@enduml

[tests/simple_classes_nodep.puml]
@startuml





/' Objects '/

abstract class Class01 {
        +{abstract} AbstractPublicMethod(int param) : bool
        +PublicMethod(int param) : bool {query}
        +{static} StaticPublicMethod(bool param) : bool
        #{abstract} _AbstractMethod(int param) : bool
        #_ProtectedMethod(int param) : bool
        #{static} _StaticProtectedMethod(bool param) : bool
        #_protected_var : int
        +public_var : int
}


class Class02 {
        +AbstractPublicMethod(int param) : bool
        -_AbstractMethod(int param) : bool
        -_PrivateMethod(T param) : bool
        -{static} _StaticPrivateMethod(bool param) : bool
        -_private_var : int
}


class Class02::ClassNested {
        -var : int
}


class Class03 <template<typename T>> {
        +Class03()
        +~Class03()
        -_data : Class01*
        -_obj : Class01*
        -_typed_obj : T*
        -_obj_list : list<Class02>
        +Method(Interface::Class04& c4) : void
}


enum Enum01 {
        VALUE_0
        VALUE_1
        VALUE_2
}


class anon_union_1::anon_struct_1 {
        +x : float
        +y : float
        +z : float
}


class anon_union_1::anon_struct_2 {
        +phi : float
        +rho : float
        +theta : float
}


class anon_union_1 {
        +vec : float
}


namespace Interface {
        class Class04 {
                +Class04()
                +~Class04()
                -_obj : Class01*
                -_val : Enum01
                -_var : T
                -_flag : bool
        }

        class Class04_derived {
                +Class04_derived()
                +~Class04_derived()
                -_var : int
        }

        enum Enum {
                A
                B
        }

        class Struct {
                +a : int
        }

        namespace Interface::NestedNamespace {
                class Class04_ns {
                        #_e : Enum
                        #_s : Struct
                }
        }
}





/' Inheritance relationships '/

.Class01 <|-- .Class02


Interface.Class04 <|-- Interface.Class04_derived


Interface.Class04_derived <|-- Interface.Interface::NestedNamespace.Class04_ns





/' Aggregation relationships '/

.Class03 "2" o-- .Class01


.Class03 *-- .Class02


Interface.Class04 o-- .Class01


Interface.Class04 *-- .Enum01


Interface.Interface::NestedNamespace.Class04_ns *-- Interface.Enum


Interface.Interface::NestedNamespace.Class04_ns *-- Interface.Struct






/' Nested objects '/

.Class02 +-- .Class02::ClassNested


.anon_union_1 +-- .anon_union_1::anon_struct_1


.anon_union_1 +-- .anon_union_1::anon_struct_2




@enduml

[tests/custom_template.puml]
{% extends 'default.puml' %}

{% block preamble %}
title "This is a title"
skinparam backgroundColor #EEEBDC
skinparam handwritten true
{% endblock %}

[tests/test_hpp2plantuml.py]
# %% Test overall system


class TestFullDiagram():

    def __init__(self):
        self._input_files = ['simple_classes_1_2.hpp', 'simple_classes_3.hpp']
        self._input_files_w = ['simple_classes_*.hpp', 'simple_classes_3.hpp']
        self._diag_saved_ref = ''
        with open(os.path.join(test_fold, 'simple_classes.puml'), 'rt') as fid:
            self._diag_saved_ref = fid.read()
        self._diag_saved_ref_nodep = ''
        with open(os.path.join(test_fold,
                               'simple_classes_nodep.puml'), 'rt') as fid:
            self._diag_saved_ref_nodep = fid.read()

    def test_full_files(self):
        self._test_full_files_helper(False)
        self._test_full_files_helper(True)

    def _test_full_files_helper(self, flag_dep=False):
        # Create first version
        file_list_ref = list(set(hpp2plantuml.hpp2plantuml.expand_file_list(
            [os.path.join(test_fold, f) for f in self._input_files])))
        diag_ref = hpp2plantuml.Diagram(flag_dep=flag_dep)
        diag_ref.create_from_file_list(file_list_ref)
        diag_render_ref = diag_ref.render()

        # Compare to saved reference
        if flag_dep:
            saved_ref = self._diag_saved_ref
        else:
            saved_ref = self._diag_saved_ref_nodep
        nt.assert_equal(saved_ref, diag_render_ref)

        # # Validate equivalent inputs

        # File expansion
        for file_list in [self._input_files, self._input_files_w]:
            file_list_c = list(set(hpp2plantuml.hpp2plantuml.expand_file_list(
                [os.path.join(test_fold, f) for f in file_list])))

            # Create from file list
            diag_c = hpp2plantuml.Diagram(flag_dep=flag_dep)
            diag_c.create_from_file_list(file_list_c)
            nt.assert_equal(diag_render_ref, diag_c.render())

            # Add from file list
            diag_c_add = hpp2plantuml.Diagram(flag_dep=flag_dep)
            diag_c_add.add_from_file_list(file_list_c)
            diag_c_add.build_relationship_lists()
            diag_c_add.sort_elements()
            nt.assert_equal(diag_render_ref, diag_c_add.render())

            # Create from first file, add from rest of the list
            diag_c_file = hpp2plantuml.Diagram(flag_dep=flag_dep)
            diag_c_file.create_from_file(file_list_c[0])
            for file_c in file_list_c[1:]:
                diag_c_file.add_from_file(file_c)
            diag_c_file.build_relationship_lists()
            diag_c_file.sort_elements()
            nt.assert_equal(diag_render_ref, diag_c_file.render())

        # String inputs
        input_str_list = []
        for file_c in file_list_ref:
            with open(file_c, 'rt') as fid:
                input_str_list.append(fid.read())

        # Create from string list
        diag_str_list = hpp2plantuml.Diagram(flag_dep=flag_dep)
        diag_str_list.create_from_string_list(input_str_list)
        nt.assert_equal(diag_render_ref, diag_str_list.render())

        # Add from string list
        diag_str_list_add = hpp2plantuml.Diagram(flag_dep=flag_dep)
        diag_str_list_add.add_from_string_list(input_str_list)
        diag_str_list_add.build_relationship_lists()
        diag_str_list_add.sort_elements()
        nt.assert_equal(diag_render_ref, diag_str_list_add.render())

        # Create from string
        diag_str = hpp2plantuml.Diagram(flag_dep=flag_dep)
        diag_str.create_from_string('\n'.join(input_str_list))
        nt.assert_equal(diag_render_ref, diag_str.render())
        # Reset and parse
        diag_str.clear()
        diag_str.create_from_string('\n'.join(input_str_list))
        nt.assert_equal(diag_render_ref, diag_str.render())

        # Manually build object
        diag_manual_add = hpp2plantuml.Diagram(flag_dep=flag_dep)
        for idx, (file_c, string_c) in enumerate(zip(file_list_ref,
                                                     input_str_list)):
            if idx == 0:
                diag_manual_add.add_from_file(file_c)
            else:
                diag_manual_add.add_from_string(string_c)
        diag_manual_add.build_relationship_lists()
        diag_manual_add.sort_elements()
        nt.assert_equal(diag_render_ref, diag_manual_add.render())

    def test_main_function(self):
        #self._test_main_function_helper(False)
        self._test_main_function_helper(True)

    def _test_main_function_helper(self, flag_dep=False):

        # List files
        file_list = [os.path.join(test_fold, f) for f in self._input_files]

        # Output to string
        with io.StringIO() as io_stream:
            sys.stdout = io_stream
            hpp2plantuml.CreatePlantUMLFile(file_list, flag_dep=flag_dep)
            io_stream.seek(0)
            # Read string output, exclude final line return
            output_str = io_stream.read()[:-1]
        sys.stdout = sys.__stdout__
        if flag_dep:
            saved_ref = self._diag_saved_ref
        else:
            saved_ref = self._diag_saved_ref_nodep
        nt.assert_equal(saved_ref, output_str)

        # Output to file
        output_fname = 'output.puml'
        for template in [None, os.path.join(test_fold,
                                            'custom_template.puml')]:
            hpp2plantuml.CreatePlantUMLFile(file_list, output_fname,
                                            template_file=template,
                                            flag_dep=flag_dep)
            output_fcontent = ''
            with open(output_fname, 'rt') as fid:
                output_fcontent = fid.read()
            if template is None:
                # Default template check
                nt.assert_equal(saved_ref, output_fcontent)
            else:
                # Check that all lines of reference are in the output
                ref_re = re.search('(@startuml)\s*(.*)', saved_ref, re.DOTALL)
                assert ref_re
                # Build regular expression: allow arbitrary text between
                # @startuml and the rest of the string
                ref_groups = ref_re.groups()
                match_re = re.compile('\n'.join([
                    re.escape(ref_groups[0]),    # @startuml line
                    '.*',                        # preamble
                    re.escape(ref_groups[1])]),  # main output
                                      re.DOTALL)
                nt.assert_true(match_re.search(output_fcontent))
        os.unlink(output_fname)

[setup.py]
# %% Custom fields

###################################################################

NAME = "hpp2plantuml"
PACKAGES = find_packages(where="src")
META_PATH = os.path.join("src", NAME, "__init__.py")
KEYWORDS = ["class"]
CLASSIFIERS = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Natural Language :: English",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.3",
    "Programming Language :: Python :: 3.4",
    "Programming Language :: Python :: 3.5",
    "Programming Language :: Python :: Implementation :: PyPy",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
INSTALL_REQUIRES = ['argparse', 'robotpy-cppheaderparser', 'jinja2']
INSTALL_REQUIRES += ['sphinx', ]
SETUP_REQUIRES = ['sphinx', 'numpydoc']
###################################################################

[setup.py]
HERE = os.path.abspath(os.path.dirname(__file__))


def read(*parts):
    """
    Build an absolute path from *parts* and and return the contents of the
    resulting file.  Assume UTF-8 encoding.
    """
    with codecs.open(os.path.join(HERE, *parts), "rb", "utf-8") as f:
        return f.read()


META_FILE = read(META_PATH)


def find_meta(meta):
    """
    Extract __*meta*__ from META_FILE.
    """
    meta_match = re.search(
        r"^__{meta}__ = ['\"]([^'\"]*)['\"]".format(meta=meta),
        META_FILE, re.M
    )
    if meta_match:
        return meta_match.group(1)
    raise RuntimeError("Unable to find __{meta}__ string.".format(meta=meta))

# %% Sphinx Build


class Sphinx(Command):
    user_options = []
    description = 'Build sphinx documentation'

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    def run(self):
        metadata = self.distribution.metadata
        src_dir = (self.distribution.package_dir or {'': ''})['']
        src_dir = os.path.join(os.getcwd(),  src_dir)
        sys.path.append('src')
        # Run sphinx by calling the main method, '--full' also adds a
        # conf.py
        sphinx.ext.apidoc.main(
            ['--private', '-H', metadata.name,
             '-A', metadata.author,
             '-V', metadata.version,
             '-R', metadata.version,
             '-o', os.path.join('doc', 'source'), src_dir]
        )
        # build the doc sources
        sphinx.cmd.build.main([os.path.join('doc', 'source'),
                               os.path.join('doc', 'build', 'html')])

[setup.py]
if __name__ == "__main__":
    setup(
        name=NAME,
        description=find_meta("description"),
        license=find_meta("license"),
        url=find_meta("uri"),
        version=find_meta("version"),
        author=find_meta("author"),
        author_email=find_meta("email"),
        maintainer=find_meta("author"),
        maintainer_email=find_meta("email"),
        keywords=KEYWORDS,
        long_description=read("README.rst"),
        packages=PACKAGES,
        package_dir={"": "src"},
        package_data={PACKAGES[0]: ['templates/*.puml']},
        include_package_data=True,
        zip_safe=False,
        classifiers=CLASSIFIERS,
        install_requires=INSTALL_REQUIRES,
        setup_requires=SETUP_REQUIRES,
        test_suite='nose.collector',
        tests_require=['nose'],
        entry_points={
            'console_scripts': ['hpp2plantuml=hpp2plantuml.hpp2plantuml:main']
        },
        cmdclass={'sphinx': Sphinx}
    )

[doc/source/conf.py]
# -*- coding: utf-8 -*-
#
# hpp2plantuml documentation build configuration file, created by
# sphinx-quickstart on Fri Dec  9 13:26:02 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath("../.."))

# Customizations

autoclass_content = 'both'
autodoc_default_flags = ['members', 'undoc-members', 'private-members']
numpydoc_show_class_members = False

# Customizations

autoclass_content = 'both'
autodoc_default_flags = ['members', 'undoc-members', 'private-members']

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.autosummary',
    'numpydoc'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = u'hpp2plantuml'
copyright = u'2016, Thibault Marin'
author = u'Thibault Marin'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'v' + u'0.8.0'
# The full version, including alpha/beta/rc tags.
release = u'v' + u'0.8.0'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
default_role = 'autolink'

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = u'hpp2plantuml ' + u'v' + u'0.8.0'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#
# html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'hpp2plantumldoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',

     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',

     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',

     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 'hpp2plantuml.tex', u'hpp2plantuml Documentation',
     u'Thibault Marin', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#
# latex_use_parts = False

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# It false, will not define \strong, \code,     itleref, \crossref ... but only
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
# packages.
#
# latex_keep_old_macro_names = True

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'hpp2plantuml', u'hpp2plantuml Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (master_doc, 'hpp2plantuml', u'hpp2plantuml Documentation',
     author, 'hpp2plantuml', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False


# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}

[doc/source/index.rst]
.. hpp2plantuml documentation master file.

hpp2plantuml documentation
==========================

.. toctree::
   :maxdepth: 4

.. _sec-intro:

Motivation
----------

The purpose of this tool is to convert C++ header files to a UML representation
in `PlantUML <https://plantuml.com>`_ syntax that can be used to generate diagrams with PlantUML.

`PlantUML <https://plantuml.com>`_ is a program rendering UML diagrams from plain text inputs using an
expressive language.

This package generates the text input to PlantUML from C++ header files.  Its
ambition is limited but it should produce reasonable conversion for simple class
hierarchies.  It aims at supporting:

- class members with properties (``private``, ``method``, ``protected``), methods with
  basic qualifiers (``static``, abstract),

- inheritance relationships,

- aggregation relationships (very basic support).

- dependency relationships

The package relies on the `CppHeaderParser <https://pypi.org/project/robotpy-cppheaderparser/>`_ package for parsing of C++ header
files.


.. _sec-module-usage:

Usage
-----

The ``hpp2plantuml`` package can be used from the command line or as a module in
other applications.

Command line
~~~~~~~~~~~~

The command line usage is (``hpp2plantuml --help``):


::

    usage: hpp2plantuml [-h] -i HEADER-FILE [-o FILE] [-d] [-t JINJA-FILE]
                        [--version]

    hpp2plantuml tool.

    optional arguments:
      -h, --help            show this help message and exit
      -i HEADER-FILE, --input-file HEADER-FILE
                            input file (must be quoted when using wildcards)
      -o FILE, --output-file FILE
                            output file
      -d, --enable-dependency
                            Extract dependency relationships from method arguments
      -t JINJA-FILE, --template-file JINJA-FILE
                            path to jinja2 template file
      --version             show program's version number and exit


Input files are added using the ``-i`` option.  Inputs can be full file paths or
include wildcards.  Note that double quotes are required when using wildcards.
The output file is selected with the ``-o`` option.  The output is a text file
following the PlantUML syntax.

For instance, the following command will generate an input file for PlantUML
(``output.puml``) from several header files.

.. code:: sh
    :name: usage-sh

    hpp2plantuml -i File_1.hpp -i "include/Helper_*.hpp" -o output.puml

To customize the output PlantUML file, templates can be used (using the ``-t``
parameter):

.. code:: sh
    :name: usage-sh-template

    hpp2plantuml -i File_1.hpp -i "include/Helper_*.hpp" -o output.puml -t template.puml

This will use the ``template.puml`` file as template.  Templates follow the `jinja <http://jinja.pocoo.org/>`_
syntax.  For instance, to add a preamble to the PlantUML output, the template
file may contain:

::

    {% extends 'default.puml' %}

    {% block preamble %}
    title "This is a title"
    skinparam backgroundColor #EEEBDC
    skinparam handwritten true
    {% endblock %}

This will inherit from the default template and override the preamble only.

Module
~~~~~~

To use as a module, simply ``import hpp2plantuml``.  The ``CreatePlantUMLFile``
function can then be used to create a PlantUML file from a set of input files.
Alternatively, the ``Diagram`` object can be used directly to build internal
objects (from files or strings).  The ``Diagram.render()`` method can be used to
produce a string output instead of writing to a text file.  See the API
documentation for more details.


Module documentation generated from docstrings
----------------------------------------------

:doc:`hpp2plantuml`

Full org-mode package documentation
-----------------------------------

:doc:`org-doc`

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

[doc/source/readthedocs-requirements.txt]
numpydoc