parse_xml.py

Go to the documentation of this file.

import os

from docs.doc_template import ClassDoc, Doc, Docs, FreeDoc
import os.path as path
import xml.etree.ElementTree as ET

DOXYGEN_CONF = 'doxygen.conf'


def parse(input_path, output_path, quiet=False, generate_xml_flag=True):
    '''Parse the files for documentation and store it in templates.

    Arguments:
    input_path -- path to the input folder or file
    output_path -- path to the output folder
    quiet -- turn on/off the messages that are generated to standard output by
             Doxygen (default = False)
    generate_xml -- use Doxygen to generate xml (default = True)

    Returns:
        A Docs template storing all the documentation in the input.
    '''
    if generate_xml_flag:
        generate_xml(input_path, output_path, quiet)

    class_docs = {}
    free_docs = {}

    for root, dirs, files in os.walk(output_path):
        for f in files:
            if f.endswith('.xml'):
                file_path = path.join(root, f)
                doc = init_doc(file_path)

                if isinstance(doc, ClassDoc):
                    class_docs[file_path] = doc

    return Docs(class_docs, free_docs)


def generate_xml(input_path, output_path, quiet=False):
    '''Parse the file for documentation and output it as in an xml format'''
    if not quiet:
        print('--------------Generating XML--------------')

    input_path = path.relpath(input_path, os.getcwd())
    conf_path = path.relpath(path.join(path.dirname(__file__), DOXYGEN_CONF))
    output_path = path.relpath(output_path)

    if not path.isdir(output_path):
        os.mkdir(output_path)

    command = '( cat {conf_path} ; echo "INPUT={input_path}" ; echo "OUTPUT_DIRECTORY={output_path}" ; echo "EXTRACT_ALL={quiet}" ) | doxygen -'.format(
        conf_path=conf_path,
        input_path=input_path,
        output_path=output_path,
        quiet='YES' if quiet else 'NO'
    )

    os.system(command)


def categorize_xml(tree):
    '''Determine the type of the object the xml tree represents.

    Arguments:
    tree -- an xml tree or path to xml string
    '''
    if isinstance(tree, str):
        tree = ET.parse(tree)

    first_compound_def = find_first_element_with_tag(tree, 'compounddef')

    if first_compound_def is None:
        return first_compound_def

    return first_compound_def.get('kind')


def init_doc(file_path):
    '''Initialize documentation given its type.

    Categorize the xml tree at file_path and initiliaze the corresponding doc
    type with the xml tree and other relevant information.

    Arguments:
    file_path -- path to the xml tree

    Returns:
        An initialized Doc
    '''
    tree = ET.parse(file_path)

    category = categorize_xml(tree)

    if category == 'class':
        return ClassDoc(tree)


def find_first_element_with_tag(tree, tag):
    if tree.getroot().tag == tag:
        return tree.getroot()

    return tree.find('.//{}'.format(tag))


def find_all_elements(tree, name, tag):
    return tree.find('.//{}'.format(tag))


def find_method_element_text(method, name):
    element = method.find(name)

    if element is None:
        return None

    out = '' if element.text is None else element.text

    for e in list(element):
        out += e.text

    return out