#============================================================================ 

#Name        : sphinx_ext.py 

#Part of     : Helium 

#

#Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

#All rights reserved.

#This component and the accompanying materials are made available

#under the terms of the License "Eclipse Public License v1.0"

#which accompanies this distribution, and is available

#at the URL "http://www.eclipse.org/legal/epl-v10.html".

#

#Initial Contributors:

#Nokia Corporation - initial contribution.

#

#Contributors:

#

#Description:

#===============================================================================

""" Custom Sphinx operations to help with Helium doc linking. """

import os

import re

import atexit

from docutils import nodes, utils

from docutils.parsers.rst import directives

import amara

tree = None

treecache = None

database_path = os.path.abspath(os.path.join(os.getcwd() + '/build', 'public_database.xml'))

# Error count for custom sphinx operations

exit_with_failure = 0 

def check_cached_database():

    """ Check the Ant database XML data is cached as needed. """

    global tree

    global treecache    

    if tree == None or treecache == None:

        f = open(database_path)

        tree = amara.parse(f)

        treecache = {}

        for project in tree.antDatabase.project:

            for x in project.xml_children:

                if hasattr(x, 'name'):

                    treecache[str(x.name)] = [str(project.name),'project']

        if hasattr(tree.antDatabase, "antlib"):

            for antlib in tree.antDatabase.antlib:

                for x in antlib.xml_children:

                    if hasattr(x, 'name'):

                        treecache[str(x.name)] = [str(antlib.name),'antlib']

def handle_hlm_role(role, _, text, lineno, inliner, options=None, content=None): # pylint: disable=W0613

    """ Process a custom Helium ReStructuredText role to link to a target, property or macro. """

    if options == None:

        options = {}

    if content == None:

        content = []

    # See if the role is used to embed a API element field

    if '[' in text:

        role_data = _embed_role_field(role, text, lineno, inliner)

    else:

        role_data = _build_link(text, lineno, inliner, options)

    return role_data

def _embed_role_field(role, text, lineno, inliner):

    """ Insert the contents of an element field. 

    These take the form of e.g. hlm-p:`build.drive[summary]`

    """

    messages = []

    node = nodes.Text('', '')

    field_match = re.search("(.*?)\[(.*?)\]", text)

    if field_match != None:

        element_name = field_match.group(1)

        field_name = field_match.group(2)

        if field_name != None and len(field_name) > 0:

            field_value = find_field_value(role, element_name, field_name)

            if field_value != None and len(field_value) > 0:

                node = nodes.Text(field_value, utils.unescape(field_value))

            else:

                messages.append(inliner.reporter.error(('Field value cannot be found for API field: "%s".' % text), line=lineno))

        else:

            messages.append(inliner.reporter.error(('Invalid field name for API value replacement: "%s".' % text), line=lineno))

        return [node], messages

def find_field_value(role, element_name, field_name):

    """ Gets the value of a field from an API element. """

    check_cached_database()

    field_value = None

    element = tree.xml_xpath('//' + roles[role] + "[name='" + element_name + "']")

    if element != None and len(element) == 1:

        field_value_list = element[0].xml_xpath(field_name)

        if field_value_list != None and len(field_value_list) == 1:

            field_value = str(field_value_list[0])

    return field_value

def _build_link(text, lineno, inliner, options):

    """ Build an HTML link to the API doc location for API element. """

    global exit_with_failure

    full_path_match = re.search(r"<document source=\"(.*?)\"", str(inliner.document))

    full_path = full_path_match.group(1)

    path_segment = full_path[full_path.index('\\doc\\') + 5:]

    dir_levels = path_segment.count('\\')

    (parent_type, parent_name) = get_root_element_name(text)

    messages = []

    # See if link can be built

    if parent_type != None and parent_name != None:

        href_text = text.replace('.', '-').lower()

        api_path_segment = 'api/helium/' + parent_type + '-' + parent_name  + '.html#' + href_text

        relative_path = ('../' * dir_levels) + api_path_segment

        api_doc_path = os.path.abspath(os.path.join(os.getcwd() + '/build/doc', api_path_segment))

        node = nodes.reference(text, utils.unescape(text), refuri=relative_path, **options)

        node = nodes.literal(text, '', node, **options)

    # Or just insert the basic property text

    else:

        messages.append(inliner.reporter.error(('Missing API doc for "%s".' % text), line=lineno))

        node = nodes.literal(text, utils.unescape(text))

        # Error occurred so record this in order to return the total number as a failure when exiting the program

        exit_with_failure += 1 

    return [node], messages

def get_root_element_name(text):

    check_cached_database()

    if text in treecache:

        return (treecache[text][1], treecache[text][0])

    return (None, None)

roles = {'hlm-t': 'target',

         'hlm-p': 'property',

         'hlm-m': 'macro',}

def setup(app):

    """ Register custom RST roles for linking Helium targets, properties and macros

    to the API documentation. """

    for role in roles.keys():

        app.add_role(role, handle_hlm_role)

    app.add_description_unit('property', 'ant-prop', 'pair: %s; property')

    app.add_description_unit('target', 'ant-target', 'pair: %s; target')

def check_for_failure():

    """ Check whether we need to exit the program with a failure due to one or more errors in a custom Sphinx operation. """

    if exit_with_failure:

        raise SystemExit("EXCEPTION: Found %d error(s) of type '(ERROR/3) Missing API doc for <property>'" % (exit_with_failure) )

# Register a cleanup routine to handle exit with failure

atexit.register(check_for_failure)